Class TimestampedWindowRangeWithHeadersQuery<K,V>

java.lang.Object
org.apache.kafka.streams.query.TimestampedWindowRangeWithHeadersQuery<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 TimestampedWindowRangeWithHeadersQuery<K,V> extends Object implements Query<ReadOnlyRecordIterator<Windowed<K>, V>>
Interactive query for retrieving records across a window-start range or for a single key's sessions, including their record headers, from a TimestampedWindowStoreWithHeaders or a SessionStoreWithHeaders.

This is the headers-aware parallel of WindowRangeQuery: it returns a ReadOnlyRecordIterator of ReadOnlyRecord elements, each carrying the windowed key, value, timestamp, and headers, whereas WindowRangeQuery returns a plain KeyValueIterator of values (no headers). Like WindowRangeQuery, this query has two mutually exclusive forms:

  • withWindowStartRange(Instant, Instant) is handled by window stores: it retrieves every key whose window start falls within the closed range [timeFrom, timeTo]. Each element's key is a Windowed describing the record's window, and ReadOnlyRecord.timestamp() is the stored record's event-time. A stored event-time is contractually 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. Because iteration can therefore throw mid-stream, always close the returned iterator (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.
  • withKey(Object) is handled by session stores: it retrieves every session for the given key. Each element's key is a Windowed whose window is the session's window. Session aggregations carry no per-record event-time of their own, so ReadOnlyRecord.timestamp() is filled from the session window's (inclusive) end timestamp. That value is validated non-negative when the window is constructed, so -- unlike the window-store form above -- this form can never throw while iterating: a session whose stored value deserializes to null is still returned, with ReadOnlyRecord.value() null (the window-store form instead throws for such an entry, as it has no event-time to surface).

Submitting the withWindowStartRange form to a session store, or the withKey form to a window store, fails with FailureReason.UNKNOWN_QUERY_TYPE.

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 or Stores.persistentSessionStoreWithHeaders). 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.

  • Method Details

    • withWindowStartRange

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

    • withKey

      public static <K,V> TimestampedWindowRangeWithHeadersQuery<K,V> withKey(K key)
      Creates a query that will retrieve the sessions (aggregation, timestamp, and headers) for the given key. Handled by session stores.
      Type Parameters:
      K - The type of the key
      V - The type of the value that will be retrieved
      Parameters:
      key - The key to retrieve

    • key

      public Optional<K> key()
      The key that was specified for this query, if this is a withKey(Object) query.

    • timeFrom

      public Optional<Instant> timeFrom()
      The inclusive lower bound of the window-start range, if this is a withWindowStartRange(Instant, Instant) query.

    • timeTo

      public Optional<Instant> timeTo()
      The inclusive upper bound of the window-start range, if this is a withWindowStartRange(Instant, Instant) query.

    • toString

      public String toString()
      Overrides:
      toString in class Object