Google Cloud Storage
The Google Cloud Storage destination writes data to objects in Google Cloud Storage. For information about supported versions, see Supported Systems and Versions.
The destination creates an object for each batch of data written to Google Cloud Storage.
With the Google Cloud Storage destination, you configure the bucket and common prefix to define where to write objects. You can use a partition prefix to specify the partition to write to. You can configure a prefix for the object name, and a time basis and data time zone for the stage. When using any data format except whole file, you can also configure a suffix for the object name and compress data with gzip before writing to Google Cloud Storage.
You also define the project ID and credentials to use when connecting to Google Cloud Storage.
The destination can generate events for an event stream. For more information about the event framework, see Dataflow Triggers Overview.
Credentials
Before writing to Google Cloud Storage, the Google Cloud Storage destination must pass credentials to Google Cloud Storage.
- Google Cloud default credentials
- Credentials in a file
- Credentials in a stage property
For details on how to configure each option, see Security in Google Cloud Stages.
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, the destination 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.
If you use datetime variables in the expression, be sure to configure the time basis for the stage.
Time Basis, Data Time Zone, and Time-Based Partition Prefixes
The time basis and the data time zone comprises the time used by the Google Cloud Storage destination to write records to a time-based partition prefix. When the configured partition prefix does not include time-based functions, 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:value("/Timestamp")}.
For details about datetime variables, see Datetime Variables.
- Processing Time
- When you use processing time as the time basis, the destination performs
writes based on the processing time and the configured partition prefix. The
processing time is the time associated with the Data Collector running the pipeline, by default. You can specify a different time zone
by configuring the Data Time Zone property. To use the processing time as
the time basis, use the following expression:
This is the default time basis.${time:now()}
- 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 based on the datetimes associated with the records, adjusting for the value specified for the Data Time Zone property.
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. If a partition does not exist, the destination creates the needed partition.
Object Names
<prefix>-<UUID>
You configure the object name prefix. For example:
sdc-c9a2db16-b5d0-44cb-b3f5-d0781cced760
.
<prefix>-<UUID>.<optional suffix>
For example: sdc-c9a2db16-b5d0-44cb-b3f5-d0781cced760.txt
.
Whole File Names
<prefix>-<results of the file name expression>
Event Generation
The Google Cloud Storage destination can generate events that you can use in an event stream. When you enable event generation, Google Cloud Storage generates event records each time the destination completes writing to an object or completes streaming a whole file.
- With the Google Cloud Storage executor to perform tasks after writing an object or whole file.
- With the Email executor to send a custom email
after receiving an event.
For an example, see Sending Email During Pipeline Processing.
- With a destination to store event information.
For an example, see Preserving an Audit Trail of Events.
For more information about dataflow triggers and the event framework, see Dataflow Triggers Overview.
Event Records
Record Header Attribute | Description |
---|---|
sdc.event.type | Event type. Uses one of the following types:
|
sdc.event.version | Integer that indicates the version of the event record type. |
sdc.event.creation_timestamp | Epoch timestamp when the stage created the event. |
- Object written
- The destination generates an object written event record when it completes writing to an object.
- 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 towholeFileProcessed
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.
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:
- 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.
- Parquet
- The destination writes a Parquet file for each partition and includes the Parquet schema in every file.
- Protobuf
- Writes a batch of messages in each file.
- 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.
- 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.
Configuring a Google Cloud Storage Destination
-
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.
-
On the GCS tab, configure the following properties:
Google Cloud Storage Property Description Bucket Bucket to use when writing records. Note: The bucket name must be DNS compliant. For more information about bucket naming conventions, see the Google Cloud Storage documentation.Common Prefix Common prefix that determines where objects are written. 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.
When using datetime variables in the expression, be sure to configure the time basis for the stage.
Data Time Zone Time zone for the destination system. Used to resolve datetimes in a time-based partition prefix.
Time Basis Time basis to use for writing to a time-based bucket or partition prefix. Use one of the following expressions:${time:now()}
- Uses the processing time as the time basis in conjunction with the specified Data Time Zone.- 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, adjusted for the specified Data Time Zone.
When the Partition Prefix property has no time component, you can ignore this property.
Default is
${time:now()}
.Object Name Prefix Defines a prefix for object names written by the destination. By default, object names start with "sdc" as follows: sdc-<UUID>
.Not required for the whole file data format.
Max Number of Retries Maximum number of times to retry the connection when the connection fails. Default is 10.
Retry Interval (ms) Time between retries in milliseconds. Default is 10,000.
-
On the Data Format tab, configure the following
property:
Data Format Property Description Data Format Data format to write data: - Avro
- Delimited
- JSON
- Parquet
- Protobuf
- SDC Record
- Text
- Whole File
-
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 Confluent Schema Registry.
Avro Schema Avro schema definition used to write the data. You can optionally use the
runtime:loadResource
function to load a schema definition stored in a runtime resource file.Register Schema Registers a new Avro schema with 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 and then enter the URL in the following format: http://<host name>:<port number>
Basic Auth User Info User information needed to connect to Confluent Schema Registry when using basic authentication. Enter the key and secret from the
schema.registry.basic.auth.user.info
setting in Schema Registry using the following format:<key>:<secret>
Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores.Look Up Schema By Method used to look up the schema in 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 Confluent Schema Registry. If the specified subject to look up has multiple schema versions, the destination 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 Confluent Schema Registry. Include Schema Includes the schema in each file. Note: Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.Avro Compression Codec The Avro compression type to use. When using Avro compression, do not enable other compression available in the destination.
-
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.
- PostgreSQL CSV - PostgreSQL comma-separated file.
- PostgreSQL Text - PostgreSQL text file.
- Custom - File that uses user-defined delimiter, escape, and quote characters.
Header Line Indicates whether to create a header line. 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 ( | ).
Record Separator String 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. Available when using a custom delimiter format.
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 ( " ).
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.
Charset Character set to use when writing data. -
For JSON data, on the Data Format tab, configure the
following properties:
JSON Property Description JSON Content Method to write JSON data: - 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. -
For Parquet data, on the Data Format tab, configure the
following properties:
Parquet Property Description Parquet Schema Location Location to load the Parquet schema from: - Parquet Schema in Record Header - Uses the schema in
the
parquetSchema
record header attribute. - In Pipeline Configuration - Uses the schema you provide in the stage configuration.
- Infer from records - The destination infers the schema from the first record of the first batch of data.
Nullable Fields Allow null values in schema fields. Default is enabled.
Parquet Compression Codec Compression type for output files: - Uncompressed
- GZIP
- LZO
- Snappy
Parquet Format Version Parquet file format version to use. Parquet Row Group Size (bytes) Maximum size in bytes of a row group being buffered in memory. The size of a row group is defined by the batch size, but you can limit it to restrict the memory usage for the write.
Parquet Page Size (bytes) Page size in bytes for compressed pages. Parquet Max Padding Size (bytes) Maximum size in bytes of allowed padding to align rows. Enable Parquet Dictionary Encoding Enables Parquet dictionary encoding. There is one dictionary page per column per group when dictionary encoding is enabled.
Parquet Dictionary Page Size (bytes) Page size in bytes for dictionary pages. - Parquet Schema in Record Header - Uses the schema in
the
-
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 Fully-qualified name for the message type to use when writing data. Use the following format:
Use a message type defined in the descriptor file.<package name>.<message type>
. -
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.
On Missing Field When a record does not include the text field, determines whether the destination reports the missing field as an error or ignores the missing field. Insert Record Separator if No Text When configured to ignore a missing text field, inserts the configured record separator string to create an empty line. When not selected, discards records without the text field.
Charset Character set to use when writing data. -
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. -
On the Credentials tab, configure the following
properties:
Credentials Property Description Project ID Google Cloud project ID to use.
Credentials Provider Provider for Google Cloud credentials: - Default credentials provider - Uses Google Cloud default credentials.
- Service account credentials file (JSON) - Uses credentials stored in a JSON service account credentials file.
- Service account credentials (JSON) - Uses JSON-formatted credentials information from a service account credentials file.
Credentials File Path (JSON) Path to the Google Cloud service account credentials file used to connect. The credentials file must be a JSON file. Enter a path relative to the Data Collector resources directory,
$SDC_RESOURCES
, or enter an absolute path.Credentials File Content (JSON) Contents of a Google Cloud service account credentials JSON file used to connect. Enter JSON-formatted credential information in plain text, or use an expression to call the information from runtime resources or a credential store.