Class TimestampedWindowKeyWithHeadersQuery<K,V>

java.lang.Object
org.apache.kafka.streams.query.TimestampedWindowKeyWithHeadersQuery<K,V>
Type Parameters:
K - Type of keys
V - Type of values
All Implemented Interfaces:
Query<ReadOnlyRecordIterator<Windowed<K>, V>>
@Evolving @Public public final class TimestampedWindowKeyWithHeadersQuery<K,V> extends Object implements Query<ReadOnlyRecordIterator<Windowed<K>, V>>
Interactive query for retrieving records of a single key across a window-start range, including their record headers, from a TimestampedWindowStoreWithHeaders.

This is the headers-aware parallel of WindowKeyQuery: it returns a ReadOnlyRecordIterator of ReadOnlyRecord elements, each carrying the windowed key, value, timestamp, and headers, whereas WindowKeyQuery returns a WindowStoreIterator of values keyed by window-start timestamp (value only, no headers). Each element's key is a Windowed whose window describes the record's window; the record's stored event-time is exposed via ReadOnlyRecord.timestamp().

As with WindowKeyQuery, a closed window-start range must be supplied (both timeFrom and timeTo); open-ended ranges are not supported.

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.persistentTimestampedWindowStoreWithHeaders). 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 window-store supplier that surfaces entries with NO_TIMESTAMP (-1) -- that entry cannot be represented, so advancing the returned ReadOnlyRecordIterator throws StreamsException at that entry. Back the store with Stores.persistentTimestampedWindowStoreWithHeaders(...) to persist timestamps and headers, or use WindowKeyQuery if headers are not needed.

Because iteration can throw mid-stream, always close the returned ReadOnlyRecordIterator (for example with try-with-resources), even when a call to next() throws; otherwise the underlying store iterator leaks and the num-open-iterators metric stays incremented.

  • Method Details

    • withKeyAndWindowStartRange

      public static <K,V> TimestampedWindowKeyWithHeadersQuery<K,V> withKeyAndWindowStartRange(K key, Instant timeFrom, Instant timeTo)
      Creates a query that will retrieve the records (value, timestamp, and headers) identified by key whose window start falls within the closed range [timeFrom, timeTo].
      Type Parameters:
      K - The type of the key
      V - The type of the value that will be retrieved
      Parameters:
      key - The key to retrieve
      timeFrom - The inclusive lower bound of the window-start range
      timeTo - The inclusive upper bound of the window-start range

    • key

      public K key()
      The key that was specified for this query.

    • timeFrom

      public Optional<Instant> timeFrom()
      The inclusive lower bound of the window-start range, if specified.

    • timeTo

      public Optional<Instant> timeTo()
      The inclusive upper bound of the window-start range, if specified.

    • toString

      public String toString()
      Overrides:
      toString in class Object