org.apache.kafka.streams.state

Interface ReadOnlyWindowStore<K,V>

Type Parameters:

K - Type of keys

V - Type of values

All Known Subinterfaces:

TimestampedWindowStore<K,V>, WindowStore<K,V>

public interface ReadOnlyWindowStore<K,V>

A window store that only supports read operations. Implementations should be thread-safe as concurrent reads and writes are expected.

Note: The current implementation of either forward or backward fetches on range-key-range-time does not obey the ordering when there are multiple local stores hosted on that instance. For example, if there are two stores from two tasks hosting keys {1,3} and {2,4}, then a range query of key [1,4] would return in the order of [1,3,2,4] but not [1,2,3,4] since it is just looping over the stores only.

Method Summary

Modifier and Type	Method and Description
KeyValueIterator<Windowed<K>,V>	all() Gets all the key-value pairs in the existing windows.
default KeyValueIterator<Windowed<K>,V>	backwardAll() Gets all the key-value pairs in the existing windows in backward order with respect to time (from end to beginning of time).
default WindowStoreIterator<V>	backwardFetch(K key, Instant timeFrom, Instant timeTo) Get all the key-value pairs with the given key and the time range from all the existing windows in backward order with respect to time (from end to beginning of time).
default KeyValueIterator<Windowed<K>,V>	backwardFetch(K keyFrom, K keyTo, Instant timeFrom, Instant timeTo) Get all the key-value pairs in the given key range and time range from all the existing windows in backward order with respect to time (from end to beginning of time).
default KeyValueIterator<Windowed<K>,V>	backwardFetchAll(Instant timeFrom, Instant timeTo) Gets all the key-value pairs that belong to the windows within in the given time range in backward order with respect to time (from end to beginning of time).
WindowStoreIterator<V>	fetch(K key, Instant timeFrom, Instant timeTo) Get all the key-value pairs with the given key and the time range from all the existing windows.
KeyValueIterator<Windowed<K>,V>	fetch(K keyFrom, K keyTo, Instant timeFrom, Instant timeTo) Get all the key-value pairs in the given key range and time range from all the existing windows.
KeyValueIterator<Windowed<K>,V>	fetch(K keyFrom, K keyTo, long timeFrom, long timeTo) Deprecated. Use fetch(Object, Object, Instant, Instant) instead
V	fetch(K key, long time) Get the value of key from a window.
WindowStoreIterator<V>	fetch(K key, long timeFrom, long timeTo) Deprecated. Use fetch(Object, Instant, Instant) instead
KeyValueIterator<Windowed<K>,V>	fetchAll(Instant timeFrom, Instant timeTo) Gets all the key-value pairs that belong to the windows within in the given time range.
KeyValueIterator<Windowed<K>,V>	fetchAll(long timeFrom, long timeTo) Deprecated. Use fetchAll(Instant, Instant) instead

Method Detail

fetch

V fetch(K key,
        long time)

Get the value of key from a window.

Parameters:

key - the key to fetch

time - start timestamp (inclusive) of the window

Returns:

The value or null if no value is found in the window

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key.

fetch

@Deprecated
WindowStoreIterator<V> fetch(K key,
                                         long timeFrom,
                                         long timeTo)

Deprecated. Use fetch(Object, Instant, Instant) instead

Get all the key-value pairs with the given key and the time range from all the existing windows.

This iterator must be closed after use.

The time range is inclusive and applies to the starting timestamp of the window. For example, if we have the following windows:

 +-------------------------------+
 |  key  | start time | end time |
 +-------+------------+----------+
 |   A   |     10     |    20    |
 +-------+------------+----------+
 |   A   |     15     |    25    |
 +-------+------------+----------+
 |   A   |     20     |    30    |
 +-------+------------+----------+
 |   A   |     25     |    35    |
 +--------------------------------
 

And we call store.fetch("A", 10, 20) then the results will contain the first three windows from the table above, i.e., all those where 10 <= start time <= 20.

For each key, the iterator guarantees ordering of windows, starting from the oldest/earliest available window to the newest/latest window.

Parameters:

key - the key to fetch

timeFrom - time range start (inclusive), where iteration starts.

timeTo - time range end (inclusive), where iteration ends.

Returns:

an iterator over key-value pairs <timestamp, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for key.

fetch

WindowStoreIterator<V> fetch(K key,
                             Instant timeFrom,
                             Instant timeTo)
                      throws IllegalArgumentException

Get all the key-value pairs with the given key and the time range from all the existing windows.

This iterator must be closed after use.

The time range is inclusive and applies to the starting timestamp of the window. For example, if we have the following windows:

 +-------------------------------+
 |  key  | start time | end time |
 +-------+------------+----------+
 |   A   |     10     |    20    |
 +-------+------------+----------+
 |   A   |     15     |    25    |
 +-------+------------+----------+
 |   A   |     20     |    30    |
 +-------+------------+----------+
 |   A   |     25     |    35    |
 +--------------------------------
 

And we call store.fetch("A", Instant.ofEpochMilli(10), Instant.ofEpochMilli(20)) then the results will contain the first three windows from the table above, i.e., all those where 10 <= start time <= 20.

For each key, the iterator guarantees ordering of windows, starting from the oldest/earliest available window to the newest/latest window.

Parameters:

key - the key to fetch

timeFrom - time range start (inclusive), where iteration starts.

timeTo - time range end (inclusive), where iteration ends.

Returns:

an iterator over key-value pairs <timestamp, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for key.

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds

backwardFetch

default WindowStoreIterator<V> backwardFetch(K key,
                                             Instant timeFrom,
                                             Instant timeTo)
                                      throws IllegalArgumentException

Get all the key-value pairs with the given key and the time range from all the existing windows in backward order with respect to time (from end to beginning of time).

This iterator must be closed after use.

The time range is inclusive and applies to the starting timestamp of the window. For example, if we have the following windows:

 +-------------------------------+
 |  key  | start time | end time |
 +-------+------------+----------+
 |   A   |     10     |    20    |
 +-------+------------+----------+
 |   A   |     15     |    25    |
 +-------+------------+----------+
 |   A   |     20     |    30    |
 +-------+------------+----------+
 |   A   |     25     |    35    |
 +--------------------------------
 

And we call store.backwardFetch("A", Instant.ofEpochMilli(10), Instant.ofEpochMilli(20)) then the results will contain the first three windows from the table above in backward order, i.e., all those where 10 <= start time <= 20.

For each key, the iterator guarantees ordering of windows, starting from the newest/latest available window to the oldest/earliest window.

Parameters:

key - the key to fetch

timeFrom - time range start (inclusive), where iteration ends.

timeTo - time range end (inclusive), where iteration starts.

Returns:

an iterator over key-value pairs <timestamp, value>, from end to beginning of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for key.

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds

fetch

@Deprecated
KeyValueIterator<Windowed<K>,V> fetch(K keyFrom,
                                                  K keyTo,
                                                  long timeFrom,
                                                  long timeTo)

Deprecated. Use fetch(Object, Object, Instant, Instant) instead

Get all the key-value pairs in the given key range and time range from all the existing windows.

This iterator must be closed after use.

Parameters:

keyFrom - the first key in the range

keyTo - the last key in the range

timeFrom - time range start (inclusive), where iteration starts.

timeTo - time range end (inclusive), where iteration ends.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key.

fetch

KeyValueIterator<Windowed<K>,V> fetch(K keyFrom,
                                      K keyTo,
                                      Instant timeFrom,
                                      Instant timeTo)
                               throws IllegalArgumentException

Get all the key-value pairs in the given key range and time range from all the existing windows.

This iterator must be closed after use.

Parameters:

keyFrom - the first key in the range

keyTo - the last key in the range

timeFrom - time range start (inclusive), where iteration starts.

timeTo - time range end (inclusive), where iteration ends.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key.

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds

backwardFetch

default KeyValueIterator<Windowed<K>,V> backwardFetch(K keyFrom,
                                                      K keyTo,
                                                      Instant timeFrom,
                                                      Instant timeTo)
                                               throws IllegalArgumentException

Get all the key-value pairs in the given key range and time range from all the existing windows in backward order with respect to time (from end to beginning of time).

This iterator must be closed after use.

Parameters:

keyFrom - the first key in the range

keyTo - the last key in the range

timeFrom - time range start (inclusive), where iteration ends.

timeTo - time range end (inclusive), where iteration starts.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from end to beginning of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key.

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds

all

KeyValueIterator<Windowed<K>,V> all()

Gets all the key-value pairs in the existing windows.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

backwardAll

default KeyValueIterator<Windowed<K>,V> backwardAll()

Gets all the key-value pairs in the existing windows in backward order with respect to time (from end to beginning of time).

Returns:

an backward iterator over windowed key-value pairs <Windowed<K>, value>, from the end to beginning of time.

Throws:

InvalidStateStoreException - if the store is not initialized

fetchAll

@Deprecated
KeyValueIterator<Windowed<K>,V> fetchAll(long timeFrom,
                                                     long timeTo)

Deprecated. Use fetchAll(Instant, Instant) instead

Gets all the key-value pairs that belong to the windows within in the given time range.

Parameters:

timeFrom - the beginning of the time slot from which to search (inclusive), where iteration starts.

timeTo - the end of the time slot from which to search (inclusive), where iteration ends.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key

fetchAll

KeyValueIterator<Windowed<K>,V> fetchAll(Instant timeFrom,
                                         Instant timeTo)
                                  throws IllegalArgumentException

Gets all the key-value pairs that belong to the windows within in the given time range.

Parameters:

timeFrom - the beginning of the time slot from which to search (inclusive), where iteration starts.

timeTo - the end of the time slot from which to search (inclusive), where iteration ends.

Returns:

an iterator over windowed key-value pairs <Windowed<K>, value>, from beginning to end of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds

backwardFetchAll

default KeyValueIterator<Windowed<K>,V> backwardFetchAll(Instant timeFrom,
                                                         Instant timeTo)
                                                  throws IllegalArgumentException

Gets all the key-value pairs that belong to the windows within in the given time range in backward order with respect to time (from end to beginning of time).

Parameters:

timeFrom - the beginning of the time slot from which to search (inclusive), where iteration ends.

timeTo - the end of the time slot from which to search (inclusive), where iteration starts.

Returns:

an backward iterator over windowed key-value pairs <Windowed<K>, value>, from end to beginning of time.

Throws:

InvalidStateStoreException - if the store is not initialized

NullPointerException - if null is used for any key

IllegalArgumentException - if duration is negative or can't be represented as long milliseconds