S3 Destination Plugin

Example #

kind: destination
spec:
  name: "s3"
  path: "cloudquery/s3"
  registry: "cloudquery"
  version: "v7.7.1"
  write_mode: "append"
  # Learn more about the configuration options at https://cql.ink/s3_destination
  spec:
    bucket: "bucket_name"
    region: "region-name" # Example: us-east-1
    path: "path/to/files/{{TABLE}}/{{UUID}}.{{FORMAT}}"
    format: "parquet" # options: parquet, json, csv
    format_spec:
      # CSV specific parameters:
      # delimiter: ","
      # skip_header: false
      # Parquet specific parameters:
      # version: "v2Latest"
      # root_repetition: "repeated"
      # max_row_group_length: 134217728 # 128 * 1024 * 1024

    # Optional parameters
    # compression: "" # options: gzip
    # no_rotate: false
    # athena: false # <- set this to true for Athena compatibility
    # write_empty_objects_for_empty_tables: false # <- set this to true if using with the CloudQuery Compliance policies
    # test_write: true # tests the ability to write to the bucket before processing the data
    # endpoint: "" # Endpoint to use for S3 API calls.
    # endpoint_skip_tls_verify # Disable TLS verification if using an untrusted certificate
    # use_path_style: false
    # batch_size: 10000 # 10K entries
    # batch_size_bytes: 52428800 # 50 MiB
    # batch_timeout: 30s # 30 seconds

path: "path/to/files/{{TABLE}}/dt={{YEAR}}-{{MONTH}}-{{DAY}}/{{UUID}}.parquet"

S3 Spec #

• bucket (string) (required)

  Bucket where to sync the files.
• region (string) (required)

  Region where bucket is located.
• local_profile (string) (optional) (default: will use current credentials)

  Local profile to use to authenticate this account with. Please note this should be set to the name of the profile.

  For example, with the following credentials file:

  [default]
  aws_access_key_id=xxxx
  aws_secret_access_key=xxxx
  
  [user1]
  aws_access_key_id=xxxx
  aws_secret_access_key=xxxx

  local_profile should be set to either default or user1.
• path (string) (required)

  Path to where the files will be uploaded in the above bucket, for example path/to/files/{{TABLE}}/{{UUID}}.parquet.

  The path supports the following placeholder variables:

  • {{TABLE}} will be replaced with the table name
  • {{TABLE_HYPHEN}} will be replaced with the table name with hyphens instead of underscores.
  • {{SYNC_ID}} will be replaced with the unique identifier of the sync. This value is a UUID and is randomly generated for each sync.
  • {{FORMAT}} will be replaced with the file format, such as csv, json or parquet. If compression is enabled, the format will be csv.gz, json.gz etc.
  • {{UUID}} will be replaced with a random UUID to uniquely identify each file
  • {{YEAR}} will be replaced with the current year in YYYY format
  • {{MONTH}} will be replaced with the current month in MM format
  • {{DAY}} will be replaced with the current day in DD format
  • {{HOUR}} will be replaced with the current hour in HH format
  • {{MINUTE}} will be replaced with the current minute in mm format

  Note that timestamps are in UTC and will be the current time at the time the file is written, not when the sync started.
• format (string) (required)

  Format of the output file. Supported values are csv, json and parquet.
• format_spec (format_spec) (optional)

  Optional parameters to change the format of the file.
• server_side_encryption_configuration (server_side_encryption_configuration) (optional)

  Optional parameters to enable server-side encryption.
• compression (string) (optional) (default: "")

  Compression algorithm to use. Supported values are "" or gzip. Not supported for parquet format.
• no_rotate (boolean) (optional) (default: false)

  If set to true, the plugin will write to one file per table. Otherwise, for every batch a new file will be created with a different .<UUID> suffix.
• athena (boolean) (optional) (default: false)

  When athena is set to true, the S3 plugin will sanitize keys in JSON columns to be compatible with the Hive Metastore / Athena. This allows tables to be created with a Glue Crawler and then queried via Athena, without changes to the table schema.
• write_empty_objects_for_empty_tables (boolean) (optional) (default: false)

  By default only tables with resources are persisted to objects during the sync. If you'd like to persist empty objects for empty tables enable this option. Useful when using CloudQuery Compliance policies to ensure all tables have their schema populated by a query engine like Athena
• test_write (boolean) (optional) (default: true)

  Ensure write access to the given bucket and path by writing a test object on each sync. If you are sure that the bucket and path are writable, you can set this to false to skip the test.
• endpoint (string) (optional) (default: "")

  Endpoint to use for S3 API calls. This is useful for S3-compatible storage services such as MinIO. Note: if you want to use path-style addressing, i.e., https://s3.amazonaws.com/BUCKET/KEY, use_path_style should be enabled, too.
• acl (string) (optional) (default: "")

  Canned ACL to apply to the object. Supported values are private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control.
• endpoint_skip_tls_verify (boolean) (optional) (default: false)

  Disable TLS verification for requests to your S3 endpoint.

  This option is intended to be used when using a custom endpoint using the endpoint option.
• use_path_style (boolean) (optional) (default: false)

  Allows to use path-style addressing in the endpoint option, i.e., https://s3.amazonaws.com/BUCKET/KEY. By default, the S3 client will use virtual hosted bucket addressing when possible (https://BUCKET.s3.amazonaws.com/KEY).
• batch_size (integer) (optional) (default: 10000)

  Number of records to write before starting a new object.
• batch_size_bytes (integer) (optional) (default: 52428800 (= 50 MiB))

  Number of bytes (as Arrow buffer size) to write before starting a new object.
• batch_timeout (duration) (optional) (default: 30s (30 seconds))

  Maximum interval between batch writes.

format_spec #

CSV

• delimiter (string) (optional) (default: ,)

  Delimiter to use in the CSV file.
• skip_header (boolean) (optional) (default: false)

  If set to true, the CSV file will not contain a header row as the first row.

JSON

Parquet

• version (string) (optional) (default: v2Latest)

  Parquet format version to use. Supported values are v1.0, v2.4, v2.6 and v2Latest. v2Latest is an alias for the latest version available in the Parquet library which is currently v2.6.

  Useful when the reader consuming the Parquet files does not support the latest version.
• root_repetition (string) (optional) (default: repeated)

  Repetition option to use for the root node. Supported values are undefined, required, optional and repeated.

  Some Parquet readers require a specific root repetition option to be able to read the file. For example, importing Parquet files into Snowflake requires the root repetition to be undefined.
• max_row_group_length (integer) (optional) (default: 134217728 (= 128 * 1024 * 1024))

  The maximum number of rows in a single row group. Use a lower number to reduce memory usage when reading the Parquet files, and a higher number to increase the efficiency of reading the Parquet files.

server_side_encryption_configuration #

• sse_kms_key_id (string) (required)

  KMS Key ID appended to S3 API calls header. Used in conjunction with server_side_encryption.
• server_side_encryption (string) (required)

  The server-side encryption algorithm used when storing the object in S3. Supported values are AES256, aws:kms and aws:kms:dsse.

Authentication #

export AWS_ACCESS_KEY_ID='{Your AWS Access Key ID}'
export AWS_SECRET_ACCESS_KEY='{Your AWS secret access key}'
export AWS_SESSION_TOKEN='{Your AWS session token}'

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

[myprofile]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

export AWS_PROFILE=myprofile

aws sts get-session-token --serial-number <YOUR_MFA_SERIAL_NUMBER> --token-code <YOUR_MFA_TOKEN_CODE> --duration-seconds 3600

export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
export AWS_SESSION_TOKEN=<YOUR_SESSION_TOKEN>