oxia.Client

class documentation

class Client: (source)

Constructor: Client(service_address, namespace, session_timeout_ms, client_identifier, request_timeout_ms)

Synchronous client for the Oxia service.

Can be used as a context manager:

    with oxia.Client('localhost:6648') as client:
        client.put('/key', b'value')

Method	`__enter__`	Undocumented
Method	`__exit__`	Undocumented
Method	`__init__`	Create a new Oxia client.
Method	`close`	Close the client and release all underlying connections.
Method	`delete`	Delete a key and its value.
Method	`delete_range`	Delete all records whose keys fall within ``[min, max)``.
Method	`get`	Retrieve the record for a key.
Method	`get_notifications`	Subscribe to change notifications for the entire database.
Method	`get_sequence_updates`	Subscribe to updates on a sequential key.
Method	`list`	List keys in the range ``[min, max)``.
Method	`put`	Associate a value with a key.
Method	`range_scan`	Scan records in the range ``[min, max)``.
Static Method	`_delete_range_single_shard`	Undocumented
Static Method	`_get_single_shard`	Undocumented
Static Method	`_list_single_shard`	Undocumented
Static Method	`_range_scan_single_shard`	Undocumented
Instance Variable	`_closed`	Undocumented
Instance Variable	`_connections`	Undocumented
Instance Variable	`_service_discovery`	Undocumented
Instance Variable	`_session_manager`	Undocumented

def __enter__(self): (source) ¶

Undocumented

def __exit__(self, exc_type, exc_val, exc_tb): (source) ¶

Undocumented

def __init__(self, service_address: str, namespace: str = 'default', session_timeout_ms: int = 30000, client_identifier: str = None, request_timeout_ms: int = 30000): (source) ¶

Create a new Oxia client.

Parameters
service_address:`str`	Oxia service address (``host:port``).
namespace:`str`	Oxia namespace. Default is ``"default"``.
session_timeout_ms:`int`	Session timeout in milliseconds for ephemeral records. Default is 30 000 ms.
client_identifier:`str`	Optional client identity string. If ``None``, a random UUID is generated.
request_timeout_ms:`int`	Deadline for each unary/finite RPC (``put``, ``delete``, ``get``, ``list``, ``range_scan``, session management). Long-lived streams (notifications, sequence updates, shard assignments) are not bounded. Default is 30 000 ms. A ``grpc.RpcError`` with ``StatusCode.DEADLINE_EXCEEDED`` is raised on timeout.

def close(self): (source) ¶

Close the client and release all underlying connections.

def delete(self, key: str, partition_key: str = None, expected_version_id: int = None) -> bool: (source) ¶

Delete a key and its value.

Parameters
key:`str`	The key to delete.
partition_key:`str`	Override shard routing.
expected_version_id:`int`	If set, the delete is conditional.

Returns
`bool`	``True`` if the record existed and was deleted, ``False`` if the key was not found.

Raises
`oxia.ex.UnexpectedVersionId`	if the version check fails.

def delete_range(self, min_key_inclusive: str, max_key_exclusive: str, partition_key: str = None): (source) ¶

Delete all records whose keys fall within ``[min, max)``.

Keys are compared using Oxia's hierarchical sort order. See: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	Start of the range (inclusive).
max_key_exclusive:`str`	End of the range (exclusive).
partition_key:`str`	If set, only the shard owning this partition key is affected.

def get(self, key: str, partition_key: str = None, comparison_type: ComparisonType = ComparisonType.EQUAL, include_value: bool = True, use_index: str = None) -> tuple[str, bytes, Version]: (source) ¶

Retrieve the record for a key.

Parameters
key:`str`	The key (or secondary-index key when use_index is set) to look up.
partition_key:`str`	Override shard routing.
comparison_type:`ComparisonType`	Key comparison mode. Default is `ComparisonType.EQUAL`. Non-equal modes query across all shards when partition_key is not set.
include_value:`bool`	If ``False``, the returned value is ``None`` (useful for metadata-only reads).
use_index:`str`	Name of a secondary index to query.

Returns
`tuple[str, bytes, Version]`	``(key, value, version)`` where key is the primary key of the matched record and value is ``bytes`` (or ``None`` if include_value is ``False``).

Raises
`oxia.ex.KeyNotFound`	if no matching record exists.

def get_notifications(self) -> Iterator[oxia.defs.Notification]: (source) ¶

Subscribe to change notifications for the entire database.

Returns an iterator that yields Notification objects for every create, modify, delete, or range-delete event. Multiple subscriptions can be active simultaneously.

Returns
`Iterator[oxia.defs.Notification]`	An iterator of `Notification` objects.

def get_sequence_updates(self, prefix_key: str, partition_key: str = None) -> oxia.defs.SequenceUpdates: (source) ¶

Subscribe to updates on a sequential key.

Returns an iterator that yields the latest key each time the sequence advances. Call ``.close()`` on the returned object when done.

Parameters
prefix_key:`str`	The key prefix for the sequence.
partition_key:`str`	Required. The partition key for shard routing.

Returns
`oxia.defs.SequenceUpdates`	A `SequenceUpdates` iterator.

Raises
`oxia.ex.InvalidOptions`	if partition_key is not set.

def list(self, min_key_inclusive: str, max_key_exclusive: str, partition_key: str = None, use_index: str = None) -> list[str]: (source) ¶

List keys in the range ``[min, max)``.

Keys are returned in Oxia's hierarchical sort order. See: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	Start of the range (inclusive).
max_key_exclusive:`str`	End of the range (exclusive).
partition_key:`str`	If set, only query the shard owning this partition key.
use_index:`str`	Name of a secondary index to query.

Returns
`list[str]`	Sorted list of keys in the range, or ``[]`` if none.

def put(self, key: str, value: str | bytes, partition_key: str = None, expected_version_id: int = None, ephemeral: bool = False, sequence_keys_deltas: list[int] = None, secondary_indexes: dict[str, str] = None) -> tuple[str, Version]: (source) ¶

Associate a value with a key.

Parameters
key:`str`	The key to write.
value:`str \| bytes`	The value (``str`` is encoded to UTF-8).
partition_key:`str`	Override shard routing with this key instead of the record key. Records sharing a partition key are co-located on the same shard.
expected_version_id:`int`	If set, the put is conditional: it succeeds only if the current version matches. Pass `EXPECTED_RECORD_DOES_NOT_EXIST` to assert the key is new.
ephemeral:`bool`	If ``True``, the record is tied to the client session and automatically deleted when the session ends.
sequence_keys_deltas:`list[int]`	Server-assigned sequential key suffixes. Requires ``partition_key``.
secondary_indexes:`dict[str, str]`	Additional index entries (``{index_name: secondary_key}``).

Returns
`tuple[str, Version]`	``(actual_key, version)``

Raises
`oxia.ex.InvalidOptions`	if options are incompatible.
`oxia.ex.UnexpectedVersionId`	if the version check fails.
`oxia.ex.SessionNotFound`	if the session for an ephemeral put no longer exists on the server.

def range_scan(self, min_key_inclusive: str, max_key_exclusive: str, partition_key: str = None, use_index: str = None) -> Iterator[tuple[str, bytes, Version]]: (source) ¶

Scan records in the range ``[min, max)``.

Returns both keys and values, unlike list which returns keys only.

Keys are returned in Oxia's hierarchical sort order. See: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	Start of the range (inclusive).
max_key_exclusive:`str`	End of the range (exclusive).
partition_key:`str`	If set, only scan the shard owning this partition key.
use_index:`str`	Name of a secondary index to query.

Returns
`Iterator[tuple[str, bytes, Version]]`	An iterator of ``(key, value, version)`` tuples.

@staticmethod

def _delete_range_single_shard(min_key_inclusive: str, max_key_exclusive: str, shard: int, stub): (source) ¶

Undocumented

@staticmethod

def _get_single_shard(shard: int, stub, key: str, comparison_type: ComparisonType, include_value: bool, use_index: str) -> tuple[str, bytes, Version]: (source) ¶

Undocumented

@staticmethod

def _list_single_shard(shard, stub, min_key_inclusive: str, max_key_exclusive: str, use_index: str) -> list: (source) ¶

Undocumented

@staticmethod

def _range_scan_single_shard(shard, stub, min_key_inclusive: str, max_key_exclusive: str, use_index: str) -> Iterator[tuple[str, bytes, Version]]: (source) ¶

Undocumented

_closed: bool = (source) ¶

Undocumented

_connections = (source) ¶

Undocumented

_service_discovery = (source) ¶

Undocumented

_session_manager = (source) ¶

Undocumented