Introduction

Kafka Connect Single Message Transforms, or SMTs, let you reshape records as they move through a connector. ValueToKey is one of the most useful transforms because it promotes fields from the record value into the record key, which directly affects partitioning, compaction, and downstream consumers.

What ValueToKey Actually Does

ValueToKey does not magically concatenate fields into a plain string. Instead, it copies the selected fields from the value and builds a key object from them. If you name more than one field, the result is a composite key structure that contains all of those fields.

A basic connector configuration looks like this:

1{
2  "transforms": "createKey",
3  "transforms.createKey.type": "org.apache.kafka.connect.transforms.ValueToKey",
4  "transforms.createKey.fields": "customerId,transactionDate"
5}

After this transform runs, the record key contains both customerId and transactionDate. That is often exactly what you want when records should be grouped by a business identity rather than by a random or missing key.

Using Multiple Fields as a Composite Key

Suppose the original value contains customer and order information. Before the transform, the key may be null. After ValueToKey, the key becomes a structured object with the selected fields.

1{
2  "key": null,
3  "value": {
4    "customerId": 42,
5    "transactionDate": "2026-03-11",
6    "amount": 19.95
7  }
8}

With the transform applied, the logical result is equivalent to this shape:

1{
2  "key": {
3    "customerId": 42,
4    "transactionDate": "2026-03-11"
5  },
6  "value": {
7    "customerId": 42,
8    "transactionDate": "2026-03-11",
9    "amount": 19.95
10  }
11}

That means multiple values absolutely can be used as the key, but the key is a composite structure, not a comma-joined text value unless you add more processing elsewhere.

Make Sure the Key Converter Matches the New Shape

This is where many connector configurations fail. If the connector previously expected a primitive key, promoting multiple value fields into the key changes the schema. Your key converter and downstream systems must be able to read that composite form.

For example, a JSON-based setup may look like this:

1{
2  "key.converter": "org.apache.kafka.connect.json.JsonConverter",
3  "key.converter.schemas.enable": true,
4  "value.converter": "org.apache.kafka.connect.json.JsonConverter",
5  "value.converter.schemas.enable": true,
6  "transforms": "createKey",
7  "transforms.createKey.type": "org.apache.kafka.connect.transforms.ValueToKey",
8  "transforms.createKey.fields": "customerId,transactionDate"
9}

If you use Avro or another schema-based format, the same principle applies. The key schema must now represent both fields. Without that, consumers and sinks may reject records or deserialize them incorrectly.

When You Need a Single Flattened Key

Sometimes a sink system expects one primitive key rather than a structured composite key. In that case, ValueToKey alone may not be enough. For a single field, ExtractField$Key can turn a structured key into one primitive field. For multiple fields, you typically need a custom SMT, an upstream producer that creates the exact key format, or a downstream system that accepts composite keys.

The main design question is not just whether multiple fields can become the key. It is whether every system in the pipeline agrees on that key representation.

Common Pitfalls

• Expecting ValueToKey to join multiple fields into a plain string automatically.
• Forgetting that a composite key changes the key schema and converter requirements.
• Choosing fields that do not actually define the grouping or partitioning you need.
• Updating the connector transform without checking consumer and sink compatibility.
• Assuming ExtractField$Key can flatten multiple fields into one primitive key by itself.

Summary

• ValueToKey can use multiple value fields as the Kafka record key.
• With multiple fields, the new key is a composite structured key.
• Key converters and downstream consumers must support the resulting key schema.
• ValueToKey is useful when partitioning should follow business identity fields.
• If you need one flattened primitive key, additional transformation or custom logic is usually required.