MapR Streams Producer

The MapR Streams Producer destination writes messages to MapR Streams.

MapR is now HPE Ezmeral Data Fabric. At times, this documentation uses "MapR" to refer to both MapR and HPE Ezmeral Data Fabric. For information about supported versions, see Supported Systems and Versions in the Data Collector documentation.

When you configure a MapR Streams Producer, you configure the topic, partition strategy, and other general properties. You configure the data type and related properties, and you can optionally add additional MapR Streams properties and supported Kafka properties.

Before you use any MapR stage in a pipeline, you must perform additional steps to enable Data Collector to process MapR data. For more information, see MapR Prerequisites in the Data Collector documentation.

Data Formats

The MapR Streams Producer processes data differently based on the data format. MapR Streams Producer can process the following types of data:

Avro

The stage 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 stage to register the Avro schema with the Confluent Schema Registry. You can also optionally include the schema definition in the message. Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.

You can include the Avro schema in the output.

You can also compress data with an Avro-supported compression codec. When using Avro compression, avoid configuring any other compression properties in the stage.

Binary

The stage writes binary data to 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.

You can use the following delimited format types:

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.
Multi Character Delimited - File that uses multiple user-defined characters to delimit fields and lines, and single user-defined escape and quote characters.

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 one record in a message. Uses the user-defined message type and the definition of the message type in the descriptor file to generate the message.

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.

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 does not contain the selected text field, the destination can report the missing field as an error or to ignore the missing field. By default, the destination reports an error.

When configured to ignore a missing text field, the destination can discard the record or write the record separator characters to create an empty line for the record. By default, the destination discards the record.

Runtime Topic Resolution

MapR Streams Producer can write a record to the topic based on an expression. When MapR Streams Producer evaluates a record, it calculates the expression based on record values and writes the record to the resulting topic.

When performing runtime topic resolution, MapR Streams Producer can write to any topic by default. You can create a white list of topics to limit the number of topics the destination attempts to use. When you create a white list, any record that resolves to an unlisted topic is sent to the stage for error handling. Use a white list when record data might resolve to invalid topic names.

Partition Strategy

The partition strategy determines how to write data to partitions. You can use a partition strategy to balance the work load or to write data semantically.

The MapR Streams Producer provides the following partition strategies:

Round-Robin

Writes each record to a different partition using a cyclical order. Use for load balancing.

Random

Writes each record to a different partition using a random order. Use for load balancing.

Expression

Writes each record to a partition based on the results of the partition expression. Use to perform semantic partitioning.

When you configure the partition expression, define the expression to evaluate to the partition where you want each record written. The expression must return a numeric value.

For example, the following expression writes records to two partitions based on the value in the Age field:

${record:value('/Age') < 21 ? 0 : 1}

The following example writes to three partitions based on the value of the Age field:

${record:value('/a') < 21 ? 0 : record:value('/a') < 55 ? 1 : 2}

Default

Writes each record using the default partition strategy that MapR Streams provides.

When you use the default partition strategy, you configure a partition expression that returns the partition key from the records, such as ${record:value('/partitionkey')}. The expression must return a string value.

The MapR Streams Producer writes each record to a partition based on a hash of the partition key.

Additional Properties

You can add custom configuration properties to MapR Streams Producer.

You can add any valid configuration property. When you add a property, enter the exact property name and the value. MapR Streams Producer does not validate the property names or values.

You can use any MapR or Kafka property supported by MapR Streams. For more information, see the MapR documentation.

If custom configurations conflict with other stage properties, the stage generates an error unless you select the Override Stage Configurations check box. With the check box selected, the custom configurations override other stage properties. For information about the necessary properties, see the MapR documentation.

Configuring a MapR Streams Producer Destination

The MapR Streams Producer destination writes messages to MapR Streams.

In the Properties panel, on the General tab, configure the following properties:


General Property	Description
Name	Stage name.
Description	Optional description.
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 Record Error	Error record handling for the stage: Discard - Discards the record. Send to Error - Sends the record to the pipeline for error handling. Stop Pipeline - Stops the pipeline.

On the MapR Streams Producer tab, configure the following properties:


MapR Streams Producer Property	Description
Runtime Topic Resolution	Evaluates an expression at runtime to determine the topic to use for each record.
Topic	Topic to use. Not available when using runtime topic resolution.
Topic Expression	Expression used to determine where each record is written when using runtime topic resolution. Use an expression that evaluates to a topic name.
Topic White List	List of valid topic names to write to when using runtime topic resolution. Use to avoid writing to invalid topics. Records that resolve to invalid topic names are passed to the stage for error handling. Use an asterisk (*) to allow writing to any topic name. By default, all topic names are valid.
Partition Strategy	Strategy to use to write to partitions: Round Robin - Takes turns writing to different partitions. Random - Writes to partitions randomly. Expression - Uses an expression to write data to different partitions. Writes records to the partitions specified by the results of the expression. Note: The expression results are written to a specified Kafka message key attribute, overwriting any existing values. Default - Uses an expression to extract a partition key from the record. Writes records to partitions based on a hash of the partition key.
Partition Expression	Expression to use with the default or expression partition strategy. When using the default partition strategy, specify an expression that returns the partition key from the record. The expression must evaluate to a string value. When using the expression partition strategy, specify an expression that evaluates to the partition where you want each record written. Partition numbers start with 0. The expression must evaluate to a numeric value. Optionally, click Ctrl + Space Bar for help with creating the expression.
One Message per Batch	For each batch, writes the records to each partition as a single message.
MapR Streams Configuration	Additional configuration properties to use. Using simple or bulk edit mode, click the Add icon and define the MapR Streams property name and value. Use the property names and values as expected by MapR. You can use MapR Streams properties and the set of Kafka properties supported by MapR Streams.
Override Stage Configurations	When configurations conflict, the properties configured in the MapR Streams Configuration property override other properties configured in the stage.

On the Data Format tab, configure the following property:


Data Format Property	Description
Data Format	Data format for messages: Avro Binary Delimited JSON Protobuf SDC Record Text

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. For more information about credential stores, see Credential Stores in the Data Collector documentation.
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 stage 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 message. 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 binary data, on the Data Format tab, configure the following property:


Binary Property	Description
Binary Field Path	Field that contains the binary data.

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 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 in the Data Collector documentation. 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: `<package name>.<message type>`. Use a message type defined in the descriptor file.

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.