diff --git a/docs/streams/upgrade-guide.html b/docs/streams/upgrade-guide.html
index 6d75d724281..71aac5c6401 100644
--- a/docs/streams/upgrade-guide.html
+++ b/docs/streams/upgrade-guide.html
@@ -133,6 +133,12 @@
More details about the new config StreamsConfig#TOPOLOGY_OPTIMIZATION
can be found in KIP-295.
+
+
+ IQv2 supports RangeQuery
that allows to specify unbounded, bounded, or half-open key-ranges, which return data in ascending (byte[]-lexicographical) order (per partition).
+ KIP-985 extends this functionality by adding .withDescendingKeys() to allow user to receive data in descending order.
+
+
Rack aware task assignment was introduced in KIP-925.
diff --git a/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java b/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
index d44bc26b74c..325a4e457a5 100644
--- a/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
+++ b/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
@@ -30,7 +30,9 @@ import java.util.Optional;
*
* A range query retrieves a set of records, specified using an upper and/or lower bound on the keys.
*
- * A scan query retrieves all records contained in the store.
+ * A scan query retrieves all records contained in the store.
+ *
+ * Keys' order is based on the serialized byte[] of the keys, not the 'logical' key order.
*
*/
@Evolving
@@ -60,7 +62,8 @@ public final class RangeQuery implements Query> {
}
/**
- * 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 implements Query> {
}
/**
- * 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 withDescendingKeys() {
diff --git a/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java b/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
index 9be1d9eceb8..f905a296256 100644
--- a/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
+++ b/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
@@ -48,13 +48,13 @@ public interface ReadOnlyKeyValueStore {
* 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 range(K from, K to);
@@ -63,13 +63,13 @@ public interface ReadOnlyKeyValueStore {
* 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 reverseRange(K from, K to) {