Amazon S3

The Amazon S3 destination writes data to Amazon S3. To write data to an Amazon Kinesis Firehose delivery system, use the Kinesis Firehose destination. To write data to Amazon Kinesis Streams, use the Kinesis Producer destination.

With the Amazon S3 destination, you configure the region, bucket, and common prefix to define where to write objects. You can use a partition prefix to specify the S3 partition to write to. You can also configure a prefix and suffix for the object name.

The Amazon S3 destination can write data asynchronously to improve performance when writing to multiple prefixes. You can configure advanced properties to tune performance.

You can configure the destination to use Amazon Web Services server-side encryption to protect the data written to Amazon S3. You can also use a proxy user and compress data with gzip when writing to Amazon S3.

The destination creates an object for each batch of data written to Amazon S3.

The Amazon S3 destination can generate events for an event stream. For more information about the event framework, see Dataflow Triggers Overview.

AWS Credentials

When Data Collector writes data to an Amazon S3 destination, it must pass credentials to Amazon Web Services.

Use one of the following methods to pass AWS credentials:

IAM roles
When Data Collector runs on an Amazon EC2 instance, you can use the AWS Management Console to configure an IAM role for the EC2 instance. Data Collector uses the IAM instance profile credentials to automatically connect to AWS.
When you use IAM roles, you do not need to specify the Access Key ID and Secret Access Key properties in the destination.
For more information about assigning an IAM role to an EC2 instance, see the Amazon EC2 documentation.
AWS access key pairs

When Data Collector does not run on an Amazon EC2 instance or when the EC2 instance doesn’t have an IAM role, you must specify the Access Key ID and Secret Access Key properties in the destination.

Tip: To secure sensitive information such as access key pairs, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.

Object Names

The Amazon S3 destination creates an object, or file, for each batch of data written. Objects generally use the following naming convention:
<prefix>-<UTC timestamp>-<counter>

For example: sdc-1462405014177-1.

You configure the object name prefix. The UTC timestamp is the time when the object is created, to the millisecond. The counter is used when multiple objects are created in the same millisecond.

You can optionally configure an object name suffix for most data formats.

Names for Whole Files

When you use the whole file data format, the object name prefix is optional. Whole files are named based on the File Name Expression whole file property. If you configure an object name prefix, whole files are named as follows:
<prefix>-<results of the file name expression>

Partition Prefix

You can use a partition prefix to organize objects by partitions. You can use the partition prefix to write to existing partitions or to create new partitions as needed. When a partition specified in the partition prefix does not exist, Amazon S3 creates the partition.

You can specify an exact partition name for the partition prefix, or you can use an expression that evaluates to a partition name.

For example, to write to partitions based on data in the Country field, you can use the following expression as the partition prefix: ${record:value('/Country')}.

With this expression, the destination writes records to partitions based on the country data in the record, and creates partitions for countries that do not already have a partition.

Time Basis and Time-Based Partition Prefixes

The time basis is the time used by the Amazon S3 destination to write records to a time-based partition prefix. When a partition prefix has no time component, you can ignore the time basis property.

A partition prefix has a time component when it includes datetime variables, such as ${YYYY()} or ${DD()}, or when it includes an expression that evaluates to a datetime value, such as ${record:valueOrDefault("/Timestamp")}.

For details about datetime variables, see Datetime Variables.

You can use the following times as the time basis:
Processing Time
When you use processing time as the time basis, the destination writes to partitions based on the processing time and the partition prefix. The processing time is the time associated with the Data Collector running the pipeline. To use the processing time as the time basis, use the following expression:
${time:now()}
This is the default time basis.
Record Time
When you use the time associated with a record as the time basis, you specify a date field in the record. The destination writes data to partitions based on the datetimes associated with the records.
To use a time associated with the record, use an expression that calls a field and resolves to a datetime value, such as ${record:value("/Timestamp")}.
For example, say you define the Partition Prefix property using the following datetime variables:
logs-${YYYY()}-${MM()}-${DD()}

If you use the time of processing as the time basis, the destination writes records to partitions based on when it processes each record. If you use the time associated with the data, such as a transaction timestamp, then the destination writes records to the partitions based on that timestamp.

Event Generation

The Amazon S3 destination can generate events that you can use in an event stream. When you enable event generation, Amazon S3 generates event records each time the destination completes writing to an object or completes streaming a whole file.

Amazon S3 events can be used in any logical way. For example:

For more information about dataflow triggers and the event framework, see Dataflow Triggers Overview.

Event Records

Event records generated by Amazon S3 destination have the following event-related record header attributes. Record header attributes are stored as String values:
Record Header Attribute Description
sdc.event.type Event type. Uses one of the following types:
  • S3 Object Written - Generated when the destination completes writing to an object.
  • wholeFileProcessed - Generated when the destination completes streaming a whole file.
sdc.event.version An integer that indicates the version of the event record type.
sdc.event.creation_timestamp Epoch timestamp when the stage created the event.
The Amazon S3 destination can generate the following types of event records:
Object written
The destination generates an object written event record when it completes writing to an object.
Object written event records have the sdc.event.type record header attribute set to S3 Object Written and include the following fields:
Field Description
bucket Bucket where the object is located.
objectKey Object key name that was written.
Whole file processed
The destination generates an event record when it completes streaming a whole file. Whole file event records have the sdc.event.type record header attribute set to wholeFileProcessed and include the following fields:
Field Description
sourceFileInfo A map of attributes about the original whole file that was processed.

The attribute names depend on the information provided by the origin system.

targetFileInfo A map of attributes about the whole file written to the destination system. The attributes include:
  • bucket - The bucket where the whole file is written.
  • objectKey - The object key name that was written.
checksum Checksum generated for the written file.

Included only when you configure the destination to include checksums in the event record.

checksumAlgorithm Algorithm used to generate the checksum.

Included only when you configure the destination to include checksums in the event record.

Server-Side Encryption

You can configure the destination to use Amazon Web Services server-side encryption (SSE) to protect data written to Amazon S3. When configured for server-side encryption, the destination passes required server-side encryption configuration values to Amazon S3. Amazon S3 uses the values to encrypt the data as it is written to Amazon S3.

When you enable server-side encryption for the destination, you select one of the following ways that Amazon S3 manages the encryption keys:
Amazon S3-Managed Encryption Keys (SSE-S3)
When you use server-side encryption with Amazon S3-managed keys, Amazon S3 manages the encryption keys for you.
AWS KMS-Managed Encryption Keys (SSE-KMS)
When you use server-side encryption with AWS Key Management Service (KMS), you specify the Amazon resource name (ARN) of the AWS KMS master encryption key that you want to use. You can also specify key-value pairs to use for the encryption context.
Customer-Provided Encryption Keys (SSE-C)
When you use server-side encryption with customer-provided keys, you specify the following information:
  • Base64 encoded 256-bit encryption key
  • Base64 encoded 128-bit MD5 digest of the encryption key using RFC 1321

For more information about using server-side encryption to protect data in Amazon S3, see the Amazon S3 documentation.

Data Formats

The Amazon S3 destination writes data to Amazon S3 based on the data format that you select. You can use the following data formats:
Avro
The destination writes records based on the Avro schema. You can use one of the following methods to specify the location of the Avro schema definition:
  • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
  • In Record Header - Use the schema included in the avroSchema record header attribute.
  • Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry. The Confluent Schema Registry is a distributed storage layer for Avro schemas. You can configure the destination to look up the schema in the Confluent Schema Registry by the schema ID or subject.

    If using the Avro schema in the stage or in the record header attribute, you can optionally configure the destination to register the Avro schema with the Confluent Schema Registry.

The destination includes the schema definition in each file.
You can compress data with an Avro-supported compression codec. When using Avro compression, avoid using other compression available in the destination.
Binary
The destination writes binary data from a single field in the record.
Delimited
The destination writes records as delimited data. When you use this data format, the root field must be list or list-map.
JSON
The destination writes records as JSON data. You can use one of the following formats:
  • Array - Each file includes a single array. In the array, each element is a JSON representation of each record.
  • Multiple objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
Protobuf
Writes a batch of messages in each file.
Uses the user-defined message type and the definition of the message type in the descriptor file to generate the messages in the file.
For information about generating the descriptor file, see Protobuf Data Format Prerequisites.
SDC Record
The destination writes records in the SDC Record data format.
Text
The destination writes data from a single text field to the destination system. When you configure the stage, you select the field to use. When necessary, merge record data into the field earlier in the pipeline.
You can configure the characters to use as record separators. By default, the destination uses a Unix-style line ending (\n) to separate records.
When a record contains no data in the text field, you can configure the destination to write the record separator characters, creating an empty line. By default, the destination discards the record.
Whole File
Streams whole files to the destination system. The destination writes the data to the file and location defined in the stage. If a file of the same name already exists, you can configure the destination to overwrite the existing file or send the current file to error.
Written files use the default permissions defined in the destination system.
You can configure the destination to generate a checksum for the written file and pass checksum information to the destination system in an event record.
For more information about the whole file data format, see Whole File Data Format.

Configuring an Amazon S3 Destination

Configure an Amazon S3 destination to write objects to Amazon S3.
  1. In the Properties panel, on the General tab, configure the following properties:
    General Property Description
    Name Stage name.
    Description Optional description.
    Produce Events Generates event records when events occur. Use for event handling.
    Required Fields Fields that must include data for the record to be passed into the stage.
    Tip: You might include fields that the stage uses.

    Records that do not include all required fields are processed based on the error handling configured for the pipeline.

    Preconditions Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions.

    Records that do not meet all preconditions are processed based on the error handling configured for the stage.

  2. On the Amazon S3 tab, configure the following properties:
    Amazon S3 Property Description
    Access Key ID

    AWS access key ID.

    Required when not using IAM roles with IAM instance profile credentials.

    Secret Access Key

    AWS secret access key.

    Required when not using IAM roles with IAM instance profile credentials.

    Region Amazon S3 region.
    Endpoint Endpoint to connect to when you select Other for the region. Enter the endpoint name.
    Bucket Bucket to use when writing objects.
    Common Prefix Common prefix that determines where objects are written.
    Delimiter Delimiter used by Amazon S3 to define the prefix hierarchy.

    Default is slash ( / ).

    Partition Prefix Optional partition prefix to specify the partition to use.

    Use a specific partition prefix or define an expression that evaluates to a partition prefix.

    Time Basis
    Time basis to use for writing to a time-based partition prefix. Use one of the following expressions:
    • ${time:now()} - Uses the processing time as the time basis.
    • An expression that calls a field and resolves to a datetime value, such as ${record:value(<date field path>)}. Uses the time associated with the record as the time basis.

    When the Partition Prefix definition has no time component, you can ignore this property.

    Default is ${time:now()}.

    Data Time Zone

    Time zone for the destination system. Used to resolve datetimes in a time-based partition prefix.

    Object Name Prefix Defines a prefix for object names written by the destination. By default, object names start with "sdc" as follows: sdc-<UTC timestamp>-<counter>.

    Not required for the whole file data format.

    Object Name Suffix Suffix to use for object names, such as txt or json. When used, the destination adds a period and the configured suffix as follows: <filename>.<suffix>.

    You can include periods within the suffix, but do not start the suffix with a period. Forward slashes are not allowed.

    Not available for the whole file data format.

    Data Format Data format to write data:
    • Avro
    • Binary
    • Delimited
    • JSON
    • Protobuf
    • SDC Record
    • Text
    • Whole File
    Compress with Gzip Compresses files with gzip before writing to Amazon S3.
  3. On the SSE tab, optionally enable server-side encryption:
    SSE Property Description
    Use Server-Side Encryption Specifies whether to enable server-side encryption.
    Server-Side Encryption Option Option that Amazon S3 uses to manage the encryption keys:
    • SSE-S3 - Use Amazon S3-managed keys.
    • SSE-KMS - Use Amazon Web Services KMS-managed keys.
    • SSE-C - Use customer-provided keys.

    Default is SSE-S3.

    AWS KMS Key ARN Amazon resource name (ARN) of the AWS KMS master encryption key. Use the following format:
    <arn>:<aws>:<kms>:<region>:<acct ID>:<key>/<key ID>

    Used for SSE-KMS encryption only.

    Encryption Context Key-value pairs to use for the encryption context. Click Add to add key-value pairs.

    Used for SSE-KMS encryption only.

    Customer Encryption Key The 256-bit and Base64 encoded encryption key to use.

    Used for SSE-C encryption only.

    Customer Encryption Key MD5 The 128-bit and Base64 encoded MD5 digest of the encryption key according to RFC 1321.

    Used for SSE-C encryption only.

  4. On the Advanced tab, optionally configure proxy information and tune performance:
    Advanced Property Description
    Use Proxy Specifies whether to use a proxy to connect to Amazon S3.
    Proxy Host Proxy host.
    Proxy Port Proxy port.
    Proxy User User name for proxy credentials.
    Proxy Password Password for proxy credentials.
    Tip: To secure sensitive information such as usernames and passwords, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
    Thread Pool Size for Parallel Uploads Size of the thread pool for parallel uploads. Used when writing to multiple partitions and writing large objects in multiple parts.

    When writing to multiple partitions, setting this property up to the number of partitions being written to can improve performance.

    For more information about this and the following properties, see the Amazon S3 TransferManager documentation.

    Multipart Upload Threshold Minimum batch size in bytes for the destination to use multipart uploads.
    Minimum Upload Part Size Minimum part size in bytes for multipart uploads.
  5. On the Data Format tab, configure the following property:
    Data Format Property Description
    Data Format Data format to write data:
    • Avro
    • Binary
    • Delimited
    • JSON
    • Protobuf
    • SDC Record
    • Text
    • Whole File
  6. For Avro data, on the Data Format tab, configure the following properties:
    Avro Property Description
    Avro Schema Location Location of the Avro schema definition to use when writing data:
    • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
    • In Record Header - Use the schema in the avroSchema record header attribute. Use only when the avroSchema attribute is defined for all records.
    • Confluent Schema Registry - Retrieve the schema from the Confluent Schema Registry.

    The destination includes the schema definition in each generated file.

    Avro Schema Avro schema definition used to write the data.

    You can optionally use the runtime:loadResource function to use a schema definition stored in a runtime resource file.

    Register Schema Select to register a new Avro schema with the Confluent Schema Registry.
    Schema Registry URLs Confluent Schema Registry URLs used to look up the schema or to register a new schema. To add a URL, click Add. Use the following format to enter the URL:
    http://<host name>:<port number>
    Look Up Schema By Method used to look up the schema in the Confluent Schema Registry:
    • Subject - Look up the specified Avro schema subject.
    • Schema ID - Look up the specified Avro schema ID.
    Schema Subject Avro schema subject to look up or to register in the Confluent Schema Registry.

    If the specified subject to look up has multiple schema versions, the origin uses the latest schema version for that subject. To use an older version, find the corresponding schema ID, and then set the Look Up Schema By property to Schema ID.

    Schema ID Avro schema ID to look up in the Confluent Schema Registry.
    Avro Compression Codec The Avro compression type to use.

    When using Avro compression, do not enable other compression available in the destination.

  7. For binary data, on the Data Format tab, configure the following property:
    Binary Property Description
    Binary Field Path Field that contains the binary data.
  8. For delimited data, on the Data Format tab, configure the following properties:
    Delimited Property Description
    Delimiter Format Format for delimited data:
    • Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
    • RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
    • MS Excel CSV - Microsoft Excel comma-separated file.
    • MySQL CSV - MySQL comma separated file.
    • Tab-Separated Values - File that includes tab-separated values.
    • Custom - File that uses user-defined delimiter, escape, and quote characters.
    Header Line Indicates whether to create a header line.
    Replace New Line Characters Replaces new line characters with the configured string.

    Recommended when writing data as a single line of text.

    New Line Character Replacement String to replace each new line character. For example, enter a space to replace each new line character with a space.

    Leave empty to remove the new line characters.

    Delimiter Character Delimiter character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    You can enter a Unicode control character using the format \uNNNN, where ​N is a hexadecimal digit from the numbers 0-9 or the letters A-F. For example, enter \u0000 to use the null character as the delimiter or \u2028 to use a line separator as the delimiter.

    Default is the pipe character ( | ).

    Escape Character Escape character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the backslash character ( \ ).

    Quote Character Quote character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the quotation mark character ( " ).

    Charset Character set to use when writing data.
  9. For JSON data, on the Data Format tab, configure the following property:
    JSON Property Description
    JSON Content Determines how JSON data is written:
    • JSON Array of Objects - Each file includes a single array. In the array, each element is a JSON representation of each record.
    • Multiple JSON Objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
    Charset Character set to use when writing data.
  10. For protobuf data, on the Data Format tab, configure the following properties:
    Protobuf Property Description
    Protobuf Descriptor File Descriptor file (.desc) to use. The descriptor file must be in the Data Collector resources directory, $SDC_RESOURCES.

    For more information about environment variables, see Data Collector Environment Configuration. For information about generating the descriptor file, see Protobuf Data Format Prerequisites.

    Message Type The fully-qualified name for the message type to use when reading data.

    Use the following format: <package name>.<message type>.

    Use a message type defined in the descriptor file.
  11. For text data, on the Data Format tab, configure the following properties:
    Text Property Description
    Text Field Path Field that contains the text data to be written. All data must be incorporated into the specified field.
    Record Separator Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use \r\n to separate records.

    By default, the destination uses \n.

    Insert Record Separator if No Text When a record does not include the text field, inserts the configured record separator string to create an empty line.

    When not selected, records without the text field are discarded.

    Charset Character set to use when writing data.
  12. For whole files, on the Data Format tab, configure the following properties:
    Whole File Property Description
    File Name Expression

    Expression to use for the file names.

    For tips on how to name files based on input file names, see Writing Whole Files.

    File Exists Action to take when a file of the same name already exists in the output directory. Use one of the following options:
    • Send to Error - Handles the record based on stage error record handling.
    • Overwrite - Overwrites the existing file.
    Include Checksum in Events Includes checksum information in whole file event records.

    Use only when the destination generates event records.

    Checksum Algorithm Algorithm to generate the checksum.