Interface ReadOnlyKeyValueStore<K,V>

Type Parameters:
K - the key type
V - the value type
All Known Subinterfaces:
KeyValueStore<K,V>, TimestampedKeyValueStore<K,V>, TimestampedKeyValueStoreWithHeaders<K,V>, VersionedBytesStore
@Public public interface ReadOnlyKeyValueStore<K,V>
A key-value store that only supports read operations. Implementations should be thread-safe as concurrent reads and writes are expected.

Please note that this contract defines the thread-safe read functionality only; it does not guarantee anything about whether the actual instance is writable by another thread, or whether it uses some locking mechanism under the hood. For this reason, making dependencies between the read and write operations on different StateStore instances can cause concurrency problems like deadlock.

  • Method Details

    • get

      V get(K key)
      Get the value corresponding to this key.
      Parameters:
      key - The key to fetch
      Returns:
      The value or null if no value is found.
      Throws:
      NullPointerException - If null is used for key.
      InvalidStateStoreException - if the store is not initialized

    • range

      KeyValueIterator<K,V> range(K from, K to)
      Get an iterator over a given range of keys. This iterator must be closed after use. The returned iterator must be safe from ConcurrentModificationExceptions and must not return null values. Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      Parameters:
      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.
      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.
      Returns:
      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

    • reverseRange

      default KeyValueIterator<K,V> reverseRange(K from, K to)
      Get a reverse iterator over a given range of keys. This iterator must be closed after use. The returned iterator must be safe from ConcurrentModificationExceptions and must not return null values. Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      Parameters:
      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.
      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.
      Returns:
      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

    • all

      KeyValueIterator<K,V> all()
      Return an iterator over all keys in this store. This iterator must be closed after use. The returned iterator must be safe from ConcurrentModificationExceptions and must not return null values. Order is not guaranteed as bytes lexicographical ordering might not represent key order.
      Returns:
      An iterator of all key/value pairs in the store, from smallest to largest bytes.
      Throws:
      InvalidStateStoreException - if the store is not initialized

    • reverseAll

      default KeyValueIterator<K,V> reverseAll()
      Return a reverse iterator over all keys in this store. This iterator must be closed after use. The returned iterator must be safe from ConcurrentModificationExceptions and must not return null values. Order is not guaranteed as bytes lexicographical ordering might not represent key order.
      Returns:
      A reverse iterator of all key/value pairs in the store, from largest to smallest key bytes.
      Throws:
      InvalidStateStoreException - if the store is not initialized

    • prefixScan

      default <PS extends Serializer<P>, P> KeyValueIterator<K,V> prefixScan(P prefix, PS prefixKeySerializer)
      Return an iterator over all keys with the specified prefix. Since the type of the prefix can be different from that of the key, a serializer to convert the prefix into the format in which the keys are stored in the stores needs to be passed to this method. The returned iterator must be safe from ConcurrentModificationExceptions and must not return null values. Since prefixScan() relies on byte lexicographical ordering and not on the ordering of the key type, results for some types might be unexpected. For example, if the key type is Integer, and the store contains keys [1, 2, 11, 13], then running store.prefixScan(1, new IntegerSerializer()) will return [1] and not [1,11,13]. In contrast, if the key type is String the keys will be sorted [1, 11, 13, 2] in the store and store.prefixScan(1, new StringSerializer()) will return [1,11,13]. In both cases prefixScan() starts the scan at 1 and stops at 2.
      Type Parameters:
      PS - Prefix Serializer type
      P - Prefix Type.
      Parameters:
      prefix - The prefix.
      prefixKeySerializer - Serializer for the Prefix key type
      Returns:
      The iterator for keys having the specified prefix.
      Throws:
      InvalidStateStoreException - if the store is not initialized

    • approximateNumEntries

      long approximateNumEntries()
      Return an approximate count of key-value mappings in this store.

      The count is not guaranteed to be exact in order to accommodate stores where an exact count is expensive to calculate.

      The accuracy of the estimate depends on the backing store. In particular, stores backed by an LSM-tree (such as the default RocksDB-based stores) may report a count that includes duplicate writes and tombstones produced when the store is restored from its changelog topic, until the backing store compacts those records away. As a result, this method can return a value substantially larger than the number of live, unique keys, especially shortly after task initialization (for example, when called from Processor.init(ProcessorContext)). Callers that need an exact live-key count should iterate the store via all() (or its variants) and count entries.

      Returns:
      an approximate count of key-value mappings in the store.
      Throws:
      InvalidStateStoreException - if the store is not initialized

    • readOnly

      default ReadOnlyKeyValueStore<K,V> readOnly(IsolationLevel isolationLevel)
      Return a read-only view of this store bound to the given IsolationLevel.

      For stores without a transaction buffer (i.e. when enable.transactional.statestores is false), the default implementation returns this — the isolation level has no observable effect. Transactional stores override this method to return a view that either consults the transaction buffer (READ_UNCOMMITTED) or reads directly from the underlying committed data (READ_COMMITTED).

      Wrapping store implementations propagate readOnly to their inner store so that transformations such as serdes or metrics are applied on top of the isolation-level-aware view.

      Parameters:
      isolationLevel - the isolation level the returned view should use for reads.
      Returns:
      a read-only view of this store using the given isolation level.