Page History

...

Current state: Under Discussion

Discussion thread: here

JIRA: here 

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

...

For stream-table joins, the join key is the stream record's key, so the processor works correctly. For stream-globalTable joins, the join key is computed from the stream record via a user-supplied KeyValueMapper and is generally different from the stream record's key. However, the current KStreamKTableJoinProcessor#doJoin implementation passes the stream record's key into ValueJoinerWithKey.apply(), not the mapped join key.

g lThe The discrepancy is not surfaced at runtime: the DSL signature pins the joiner's first type parameter to the stream key type K, and the implementation passes passes record.key()(also K), so types align, and no error or warning is raised. The join still matches records correctly because matching is done by the KeyValueMapper, not the joiner. However, KIP-149 specified readOnlyKey would be the join key, which for stream–globalTable joins is the mapped key, not the stream key. Any joiner that uses readOnlyKey will silently produce output values that encode the stream key where it is expected to be the join key, with no error or warning surfaced.

...

/** As {@link #join(GlobalKTable, KeyValueMapper, ValueJoiner)}, but the joiner's {@code readOnlyKey} is the mapped join key. */
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> joinOnMappedKeyjoinByMappedKey(
    final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super GlobalKey, ? super V, ? super GlobalValue, ? extends VOut> joiner
)

 /** As above, with a {@link Named} processor name. */
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> joinOnMappedKeyjoinByMappedKey(
    final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super GlobalKey, ? super V, ? super GlobalValue, ? extends VOut> joiner,
    final Named named
)

/** As {@link #leftJoin(GlobalKTable, KeyValueMapper, ValueJoiner)}, but the joiner's {@code readOnlyKey} is the mapped join key. */
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> leftJoinOnMappedKeyleftJoinByMappedKey(
    final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super GlobalKey, ? super V, ? super GlobalValue, ? extends VOut> joiner
)

/** As above, with a {@link Named} processor name. */
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> leftJoinOnMappedKeyleftJoinByMappedKey(
    final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super GlobalKey, ? super V, ? super GlobalValue, ? extends VOut> joiner,
    final Named named
)

...

The existing KStream.join(GlobalKTable, KeyValueMapper, ValueJoinerWithKey) and KStream.leftJoin(GlobalKTable, KeyValueMapper, ValueJoinerWithKey) overloads are retained for backwards compatibility. They continue to pass the stream record's key into the joiner, but are marked as @Deprecated, and are targeted to be removed in a future major release. Furthermore, an additional comment for each deprecated method stressing that the readOnlyKey is currently the stream key, not the mapped join key is added.

/**
 * <p><b>Warning:</b> {@code readOnlyKey} is the {@code KStream} record's key, <b>not</b> the join key
 * produced by {@code keySelector}. Unlike {@link #join(KTable, ValueJoinerWithKey) KStream-KTable} and
 * {@link #join(KStream, ValueJoinerWithKey, JoinWindows) KStream-KStream} joins — where the stream key
 * <em>is</em> the join key — {@link GlobalKTable} joins derive the join key via {@code keySelector}, so
 * {@code readOnlyKey} does <b>not</b> necessarily match the key of the {@link GlobalKTable} record being joined.
 */
@Deprecated
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> join(
	final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super K, ? super V, ? super GlobalValue, ? extends VOut> joiner
)

@Deprecated
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> join(
	final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super K, ? super V, ? super GlobalValue, ? extends VOut> joiner,
    final Named named
)

@Deprecated
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> leftJoin(
	final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super K, ? super V, ? super GlobalValue, ? extends VOut> joiner
)

@Deprecated
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> leftJoin(
	final GlobalKTable<GlobalKey, GlobalValue> globalTable,
    final KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
    final ValueJoinerWithKey<? super K, ? super V, ? super GlobalValue, ? extends VOut> joiner,
    final Named named
)

...

• The existing join/leftJoin stream-globalTable overloads taking ValueJoinerWithKey are deprecated. Existing applications continue to compile and run unchanged, but the compiler will emit deprecation warnings, and the methods will be removed in a future major release.

• The new joinOnMappedKey joinByMappedKey and leftJoinOnMappedKey leftJoinByMappedKey methods are additive. Existing code compiles and runs unchanged; migration is required only before the deprecated overloads are removed.

• Stream-globalTable overloads taking ValueJoiner (no key access) are unaffected.

• Migration guidance for the new join methods will be added to the Streams upgrade guide.

...