K
- The key typeV
- The value typepublic interface VersionedKeyValueStore<K,V> extends StateStore
put(Object, Object, long)
with the same key and timestamp will replace the first.
Each store instance has an associated, fixed-duration "history retention" which specifies
how long old record versions should be kept for. In particular, a versioned store guarantees
to return accurate results for calls to get(Object, long)
where the provided timestamp
bound is within history retention of the current observed stream time. (Queries with timestamp
bound older than the specified history retention are considered invalid.)
The store's "history retention" also doubles as its "grace period," which determines how far back in time writes to the store will be accepted. A versioned store will not accept writes (inserts, updates, or deletions) if the timestamp associated with the write is older than the current observed stream time by more than the grace period.
Modifier and Type | Field and Description |
---|---|
static long |
PUT_RETURN_CODE_NOT_PUT |
static long |
PUT_RETURN_CODE_VALID_TO_UNDEFINED |
Modifier and Type | Method and Description |
---|---|
VersionedRecord<V> |
delete(K key,
long timestamp)
Delete the value associated with this key from the store, at the specified timestamp
(if there is such a value), and return the deleted value.
|
VersionedRecord<V> |
get(K key)
Get the current (i.e., latest by timestamp) record associated with this key.
|
VersionedRecord<V> |
get(K key,
long asOfTimestamp)
Get the record associated with this key as of the specified timestamp (i.e.,
the existing record with the largest timestamp not exceeding the provided
timestamp bound).
|
long |
put(K key,
V value,
long timestamp)
Add a new record version associated with the specified key and timestamp.
|
close, flush, getPosition, init, init, isOpen, name, persistent, query
static final long PUT_RETURN_CODE_VALID_TO_UNDEFINED
static final long PUT_RETURN_CODE_NOT_PUT
long put(K key, V value, long timestamp)
If the timestamp associated with the new record version is older than the store's grace period (i.e., history retention) relative to the current observed stream time, then the record will not be added.
key
- The keyvalue
- The value, it can be null
. null
is interpreted as a delete.timestamp
- The timestamp for this record version-1
and
Long.MIN_VALUE
carry specific meanings. -1
indicates that the
record that was put is the latest record version for its key, and therefore the
validTo timestamp is undefined. Long.MIN_VALUE
indicates that the record
was not put, due to grace period having been exceeded.NullPointerException
- If null
is used for key.InvalidStateStoreException
- if the store is not initializedVersionedRecord<V> delete(K key, long timestamp)
This operation is semantically equivalent to #get(key, timestamp)
followed by #put(key, null, timestamp)
.
If the timestamp associated with this deletion is older than the store's grace period
(i.e., history retention) relative to the current observed stream time, then the deletion
will not be performed and null
will be returned.
As a consequence of the above, the way to delete a record version is #get(key)
or #get(key, timestamp)
and use the returned VersionedRecord.timestamp()
in a call to this
delete(key, timestamp)
method, as the returned timestamp may be older than
the store's grace period (i.e., history retention) and will therefore not take place.
Instead, you should pass a business logic inferred timestamp that specifies when
the delete actually happens. For example, it could be the timestamp of the currently
processed input record or the current stream time.
This operation is semantically equivalent to #get(key, timestamp)
followed by #put(key, null, timestamp)
, with
a caveat that if the deletion timestamp is older than the store's grace period
(i.e., history retention) then the return value is always null
, regardless
of what #get(key, timestamp)
would return.
key
- The keytimestamp
- The timestamp for this deletenull
if no such record exists
(including if the deletion timestamp is older than this store's history
retention time, i.e., the store no longer contains data for the provided
timestamp). Note that the record timestamp r.timestamp()
of the
returned VersionedRecord
may be smaller than the provided deletion
timestamp.NullPointerException
- If null
is used for key.InvalidStateStoreException
- if the store is not initializedVersionedRecord<V> get(K key)
key
- The key to fetchnull
if there is no current record for this key.NullPointerException
- If null is used for key.InvalidStateStoreException
- if the store is not initializedVersionedRecord<V> get(K key, long asOfTimestamp)
key
- The key to fetchasOfTimestamp
- The timestamp bound. This bound is inclusive; if a record
(for the specified key) exists with this timestamp, then
this is the record that will be returned.null
if no such record exists
(including if the provided timestamp bound is older than this store's history
retention time, i.e., the store no longer contains data for the provided
timestamp). Note that the record timestamp r.timestamp()
of the
returned VersionedRecord
may be smaller than the provided timestamp
bound. Additionally, if the latest record version for the key is eligible
for the provided timestamp bound, then that record will be returned even if
the timestamp bound is older than the store's history retention.NullPointerException
- If null is used for key.InvalidStateStoreException
- if the store is not initialized