Specifies the name of the column where the provider stores the message key for each record.

Data Type

string

Default Value

""

Remarks

Set this property to expose message key data as a column in the table schema. If this property is not set, message key data is not included in the result set. See MessageKeyType for details on how the driver interprets and formats message keys.

In addition to this connection-level behavior, you can set the Kafka message key for an individual INSERT statement by including one of two reserved columns in the INSERT. The driver treats these columns as routing directives: they are consumed to build the key and are never written into the message themselves.

• MessageKeyColumn (reference form): the value names which inserted column or columns form the key. Supply a single column name for a primitive key (for example, Id); an object prefix to use a whole nested object (for example, Address, which builds the key from every Address.* column with the prefix stripped); or a comma-separated list to use a subset (for example, Address.City, Address.Zip). Columns selected this way are written to both the message key and the message value. Supplying this column in an INSERT overrides the connection-level MessageKeyColumn property for that statement only.
• MessageKeyColumnValue (literal form): the value is used verbatim as the message key and is never looked up as a column. A NULL value publishes a keyless message. This form requires a primitive MessageKeyType (String, Long, Integer, Float, or Double); other types (JSON, Avro, XML, CSV, or Binary) are rejected.

MessageKeyType must be set to a value other than Null to use either MessageKeyValue or MessageKeyColumn otherwise the INSERT fails. The driver also reports an error with the following conditions: 1) Both MessageKeyValue and MessageKeyColumn appear in one INSERT. 2) A MessageKeyColumn target matches no inserted column 3) The topic has a registered key schema. 4) When UseBulkMessages is true and UseConfluentAvroFormat is false.

Kafka assigns a partition by hashing the message key bytes, and the driver serializes complex-key fields in the order the columns appear in the INSERT. Emit the key-contributing columns (or list the targets) in a consistent order for a given topic; otherwise rows with the same logical key can produce different key bytes and land in different partitions.

If an INSERT also supplies an explicit Partition column, the explicit partition takes precedence. The message is written to that partition regardless of the key.