Class TimestampedRangeWithHeadersQuery<K,V>

java.lang.Object
org.apache.kafka.streams.query.TimestampedRangeWithHeadersQuery<K,V>
Type Parameters:
K - Type of keys
V - Type of values
All Implemented Interfaces:
Query<ReadOnlyRecordIterator<K,V>>
@Evolving @Public public final class TimestampedRangeWithHeadersQuery<K,V> extends Object implements Query<ReadOnlyRecordIterator<K,V>>
Interactive query for issuing range queries and scans over a TimestampedKeyValueStoreWithHeaders, returning each record together with its headers.

This is the headers-aware parallel of TimestampedRangeQuery: it returns a ReadOnlyRecordIterator of ReadOnlyRecord elements, each carrying the key, value, timestamp, and headers, whereas TimestampedRangeQuery returns a KeyValueIterator of ValueAndTimestamp (value and timestamp only, no headers).

A range query retrieves a set of records, specified using an upper and/or lower bound on the keys. A scan query (no bounds) retrieves all records contained in the store. Keys' order is based on the serialized byte[] of the keys, not the 'logical' key order.

Headers are persisted and returned only when the store is backed by a native headers store, i.e. built with a KIP-1271 WithHeaders byte-store supplier (e.g. Stores.persistentTimestampedKeyValueStoreWithHeaders). A WithHeaders store built over a legacy (non-headers) supplier cannot persist headers, so the store-served reads come back with empty headers().

Against a plain store not built with the WithHeaders builder at all, this query type is unsupported and fails with FailureReason.UNKNOWN_QUERY_TYPE.

Each element is a ReadOnlyRecord, whose timestamp is non-negative. If the backing store does not persist timestamps -- for example a WithHeaders store built over a plain KeyValueStore supplier, which surfaces every entry with NO_TIMESTAMP (-1) -- that entry cannot be represented, so advancing the returned ReadOnlyRecordIterator throws StreamsException at that entry. Back the store with Stores.persistentTimestampedKeyValueStoreWithHeaders(...) to persist timestamps and headers, or use TimestampedRangeQuery if headers are not needed.

  • Method Details

    • withRange

      public static <K,V> TimestampedRangeWithHeadersQuery<K,V> withRange(K lower, K upper)
      Interactive range query using a lower and upper bound to filter the keys returned.
      Type Parameters:
      K - The key type
      V - The value type
      Parameters:
      lower - The key that specifies the lower bound of the range
      upper - The key that specifies the upper bound of the range

    • withUpperBound

      public static <K,V> TimestampedRangeWithHeadersQuery<K,V> withUpperBound(K upper)
      Interactive range query using an upper bound to filter the keys returned.
      Type Parameters:
      K - The key type
      V - The value type
      Parameters:
      upper - The key that specifies the upper bound of the range

    • withLowerBound

      public static <K,V> TimestampedRangeWithHeadersQuery<K,V> withLowerBound(K lower)
      Interactive range query using a lower bound to filter the keys returned.
      Type Parameters:
      K - The key type
      V - The value type
      Parameters:
      lower - The key that specifies the lower bound of the range

    • withNoBounds

      public static <K,V> TimestampedRangeWithHeadersQuery<K,V> withNoBounds()
      Interactive scan query that returns all records in the store.
      Type Parameters:
      K - The key type
      V - The value type

    • withDescendingKeys

      public TimestampedRangeWithHeadersQuery<K,V> withDescendingKeys()
      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.
      Returns:
      a new query instance with the descending flag set.

    • withAscendingKeys

      public TimestampedRangeWithHeadersQuery<K,V> withAscendingKeys()
      Set the query to return the serialized byte[] of the keys in ascending order. Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      Returns:
      a new query instance with the ascending flag set.

    • lowerBound

      public Optional<K> lowerBound()
      The lower bound of the query, if specified.

    • upperBound

      public Optional<K> upperBound()
      The upper bound of the query, if specified.

    • resultOrder

      public ResultOrder resultOrder()
      Determines if the serialized byte[] of the keys in ascending or descending or unordered order. Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      Returns:
      the order of the returned records based on the serialized byte[] of the keys (can be unordered, ascending, or descending).