class tensorstore.KvStore

Key-value store that maps an ordered set of byte string keys to byte string values.

This is used as the storage interface for most of the TensorStore drivers.

The actual storage mechanism is determined by the driver.


>>> store = await{'driver': 'memory'})
>>> await store.write(b'a', b'value')
>>> await'a')
KvStore.ReadResult(state='value', value=b'value', stamp=KvStore.TimestampedStorageGeneration(...))
>>> await'b')
KvStore.ReadResult(state='missing', value=b'', stamp=KvStore.TimestampedStorageGeneration(...))
>>> await store.list()

By default, operations are non-transactional, but transactional operations are also supported:

>>> txn = ts.Transaction()
>>> store.with_transaction(txn)[b'a']
>>> store.with_transaction(txn)[b'a'] = b'new value'
>>> store.with_transaction(txn)[b'a']
b'new value'
>>> store[b'a']
>>> txn.commit_sync()
>>> store[b'a']
b'new value'


class Spec

Parsed representation of a JSON key-value store specification.

class KeyRange

Half-open interval of byte string keys, according to lexicographical order.

class TimestampedStorageGeneration

Specifies a storage generation identifier and a timestamp.

class ReadResult

Specifies the result of a read operation.


static open(spec: KvStore.Spec | Any, *, ...) Future[KvStore]

Opens a key-value store.


path : str

Path prefix within the base key-value store.

url : str

URL representation of the key-value store specification.

base : KvStore | None

Underlying key-value store, if this is a key-value store adapter.

spec(*, retain_context: bool | None = None, ...) KvStore.Spec

Spec that may be used to re-open or re-create the key-value store.

copy() KvStore

Returns a copy of the key-value store.


list(...) Future[list[bytes]]

Lists the keys in the key-value store.

read(key: str, *, ...) Future[KvStore.ReadResult]

Reads the value of a single key.

write(key: str, ...) Future[KvStore.TimestampedStorageGeneration]

Writes or deletes a single key.

delete_range(range: KvStore.KeyRange) Future[None]

Deletes a key range.

experimental_copy_range_to(target: KvStore, ...) Future[None]

Copies a range of keys.

Synchronous I/O

__getitem__(key: str) bytes

Synchronously reads the value of a single key.

__setitem__(key: str, value: str | None)

Synchronously writes the value of a single key.

__delitem__(key: str) None

Synchronously deletes a single key.


__add__(suffix: str) KvStore

Returns a key-value store with the suffix appended to the path.

__truediv__(component: str) KvStore

Returns a key-value store with an additional path component joined to the path.


transaction : Transaction | None

Transaction bound to this key-value store.

with_transaction(transaction: Transaction | None) KvStore

Returns a transaction-bound view of this key-value store.

String representation

__repr__() str

Returns a string representation based on the JSON representation.