KeyValue schema encoding types INLINE vs SEPARATED

[kasparjarek]

I have a few questions regarding KeyValue schema encoding types (INLINE vs SEPARATED). I have seen conflicting answers from AI bots and was unable to find clear information in the documentation.

1. Is it true that when using INLINE encoding, the key is not used for routing decisions and therefore the ordering guarantees of the Key_Shared subscription type are lost?
2. What are the practical advantages and disadvantages of these two encoding types? If the statement above is true, why would I ever want to use INLINE type?

Thank you

[Slymaster]

The key inside your KeyValue<K,V> object and the Pulsar message key used for routing are separate in the Java client.

• INLINE serializes both parts into the payload. It does not automatically copy the object's key into the message-key metadata.
• SEPARATED serializes the object's key into the message-key metadata and puts only the value in the payload.

You can see both paths in TypedMessageBuilderImpl, v4.0.8 and its separated-key implementation.

Your first statement is correct if you use INLINE without setting a message key or ordering key: Key_Shared cannot group messages by a key that exists only inside the payload. However, INLINE itself does not prevent keyed routing. You can supply the message key separately:

var schema = Schema.KeyValue(
        Schema.STRING, Schema.STRING, KeyValueEncodingType.INLINE);

var producer = client.newProducer(schema)
        .topic("persistent://public/default/events")
        .enableBatching(false)
        .create();

producer.newMessage()
        .key("customer-42")
        .value(new KeyValue<>("customer-42", "updated"))
        .send();

This is supported by the Java client's tests.

SEPARATED is convenient when the object's key should also be the routing/compaction key. INLINE is useful when you want a self-contained serialized key/value payload, or want routing to use a different key.

For either encoding, Key_Shared requires batching to be disabled or key-based. Default batching can mix keys and defeat the intended routing.