root
/
kafka
mirror of https://github.com/apache/kafka.git
1
0
Fork 0
Code Issues Actions 3 Packages Projects Releases Wiki Activity

KAFKA-15527: Update docs and JavaDocs (#14600) 

Part of KIP-985.

Updates JavaDocs for `RangeQuery` and `ReadOnlyKeyValueStore` with regard to ordering guarantees.
Updates Kafka Streams upgrade guide with KIP information.

Reviewer: Matthias J. Sax <matthias@confluent.io>
This commit is contained in:
Hanyu Zheng 2023-10-26 17:48:28 -07:00 committed by GitHub
parent 339d2556c6
commit 834f72b03d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 17 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/streams/upgrade-guide.html
View File

@ -133,6 +133,12 @@
More details about the new config <code>StreamsConfig#TOPOLOGY_OPTIMIZATION</code> can be found in <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-295%3A+Add+Streams+Configuration+Allowing+for+Optional+Topology+Optimization">KIP-295</a>.
</p>
<h3><a id="streams_api_changes_370" href="#streams_api_changes_370">Streams API changes in 3.7.0</a></h3>
<p>
IQv2 supports <code>RangeQuery</code> that allows to specify unbounded, bounded, or half-open key-ranges, which return data in ascending (byte[]-lexicographical) order (per partition).
<a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-985%3A+Add+reverseRange+and+reverseAll+query+over+kv-store+in+IQv2">KIP-985</a> extends this functionality by adding <code>.withDescendingKeys()<code> to allow user to receive data in descending order.
</p>
<h3><a id="streams_api_changes_360" href="#streams_api_changes_360">Streams API changes in 3.6.0</a></h3>
<p>
Rack aware task assignment was introduced in <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-925%3A+Rack+aware+task+assignment+in+Kafka+Streams">KIP-925</a>.

10
streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
View File

@ -30,7 +30,9 @@ import java.util.Optional;
* <p>
* A range query retrieves a set of records, specified using an upper and/or lower bound on the keys.
* <p>
* A scan query retrieves all records contained in the store.
* A scan query retrieves all records contained in the store.
* <p>
* Keys' order is based on the serialized byte[] of the keys, not the 'logical' key order.
* <p>
*/
@Evolving
@ -60,7 +62,8 @@ public final class RangeQuery<K, V> implements Query<KeyValueIterator<K, V>> {
}
/**
* Determines if the query keys are in ascending order.
* Determines if the serialized byte[] of the keys in ascending order.
* Order is based on the serialized byte[] of the keys, not the 'logical' key order.
* @return true if ascending, false otherwise.
*/
public boolean isKeyAscending() {
@ -68,7 +71,8 @@ public final class RangeQuery<K, V> implements Query<KeyValueIterator<K, V>> {
}
/**
* Set the query to return keys in descending order.
* Set the query to return the serialized byte[] of the keys in descending order.
* Order is based on the serialized byte[] of the keys, not the 'logical' key order.
* @return a new RangeQuery instance with descending flag set.
*/
public RangeQuery<K, V> withDescendingKeys() {

8
streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
View File

@ -48,13 +48,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
* Get an iterator over a given range of keys. This iterator must be closed after use.
* The returned iterator must be safe from {@link java.util.ConcurrentModificationException}s
* and must not return null values.
* Order is not guaranteed as bytes lexicographical ordering might not represent key order.
* Order is based on the serialized byte[] of the keys, not the 'logical' key order.
*
* @param from The first key that could be in the range, where iteration starts from.
* A null value indicates that the range starts with the first element in the store.
* @param to The last key that could be in the range, where iteration ends.
* A null value indicates that the range ends with the last element in the store.
* @return The iterator for this range, from smallest to largest bytes.
* @return The iterator for this range, from key with the smallest bytes to the key with the largest bytes of keys.
* @throws InvalidStateStoreException if the store is not initialized
*/
KeyValueIterator<K, V> range(K from, K to);
@ -63,13 +63,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
* Get a reverse iterator over a given range of keys. This iterator must be closed after use.
* The returned iterator must be safe from {@link java.util.ConcurrentModificationException}s
* and must not return null values.
* Order is not guaranteed as bytes lexicographical ordering might not represent key order.
* Order is based on the serialized byte[] of the keys, not the 'logical' key order.
*
* @param from The first key that could be in the range, where iteration ends.
* A null value indicates that the range starts with the first element in the store.
* @param to The last key that could be in the range, where iteration starts from.
* A null value indicates that the range ends with the last element in the store.
* @return The reverse iterator for this range, from largest to smallest key bytes.
* @return The iterator for this range, from key with the smallest bytes to the key with the largest bytes of keys.
* @throws InvalidStateStoreException if the store is not initialized
*/
default KeyValueIterator<K, V> reverseRange(K from, K to) {