oxia.Client

class documentation

class Client: (source)

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

Client is the main entry point to the Oxia Python client

Method	`__init__`	Create a new Oxia client instance.
Method	`close`	Close closes the client and all underlying connections
Method	`delete`	Removes the key and its associated value from the data store.
Method	`delete_range`	Deletes any records with keys within the specified range.
Method	`get`	Returns the value associated with the specified key.
Method	`get_notifications`	Creates a new subscription to receive the notifications from Oxia for any change that is applied to the database
Method	`get_sequence_updates`	Subscribe to the updates happening on a sequential key.
Method	`list`	List all the keys within the specified range.
Method	`put`	Associates a value with a key
Method	`range_scan`	perform a scan for existing records with any keys within the specified range.
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 __init__(self, service_address: str, namespace: str = 'default', session_timeout_ms: int = 30000, client_identifier: str = None): (source) ¶

Create a new Oxia client instance.

Initializes an instance of the class that manages service discovery, session management, and connection pooling. The constructor is responsible for setting up the required infrastructure to communicate with the service discovery system and maintain sessions.

Parameters
service_address:`str`	The Oxia service address to connect to.
namespace:`str`	The namespace to which this client belongs. Default is "default".
session_timeout_ms:`int`	Duration of the session timeout in milliseconds. Default is 30,000 ms.
client_identifier:`str`	A unique identifier for the client. If None, a default identifier will be generated internally.

def close(self): (source) ¶

Close closes the client and all underlying connections

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

Removes the key and its associated value from the data store.

The delete operation can be made conditional on that the record hasn't changed from a specific existing version by passing the [ExpectedVersionId] option.

Parameters
key:`str`	the key to delete
partition_key:`str`	the partition key to use (instead of the actual record key)
expected_version_id:`int`	the expected version id of the record to delete. If not specified, the delete operation is not conditional.

Returns
`bool`	true if the record was deleted, false otherwise

Raises
`oxia.ex.KeyNotFound`	if the record does not exist
`oxia.ex.UnexpectedVersionId`	if the expected version id does not match the current version id of the record

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

Deletes any records with keys within the specified range.

Note: Oxia uses a custom sorting order that treats `/` characters in a special way. Refer to this documentation for the specifics: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	the minimum key to delete from
max_key_exclusive:`str`	the maximum key to delete to (exclusive)
partition_key:`str`	if set, the delete range will be applied to the shard with the specified partition key.

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

Returns the value associated with the specified key.

In addition to the value, a version object is also returned, with information about the record state.

Parameters
key:`str`	the key to retrieve
partition_key:`str`	the partition key to use (instead of the actual record key)
comparison_type:`ComparisonType`	the comparison type to use
include_value:`bool`	whether to include the value in the result
use_index:`str`	the name of the secondary index to use

Returns
`(str, str, Version)`	(key, value, version)

Raises
`oxia.ex.KeyNotFound`	if the record does not exist

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

Creates a new subscription to receive the notifications from Oxia for any change that is applied to the database

Returns
`Iterator[oxia.Notification]`	an iterator over the notifications. Each notification is a Notification object.

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

Subscribe to the updates happening on a sequential key.

Multiple updates can be collapsed into one single event with the highest sequence.

Parameters
prefix_key:`str`	the prefix for the sequential key.
partition_key:`str`	the partition key to use (this is required)

Returns
`SequenceUpdates`	a SequenceUpdates object that can be used to iterate over the updates. Should be closed when done.

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

List all the keys within the specified range.

Note: Oxia uses a custom sorting order that treats `/` characters in special way. Refer to this documentation for the specifics: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	the minimum key to list from (inclusive).
max_key_exclusive:`str`	the maximum key to list to (exclusive).
partition_key:`str`	if set, the list will be applied to the shard with the specified partition key.
use_index:`str`	if set, the list will be applied to the secondary index with the specified name.

Returns
`list[str]`	the list of keys within the specified range.

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

Associates a value with a key

There are few options that can be passed to the Put operation:

The Put operation can be made conditional on that the record hasn't changed from a specific existing version by passing the `expected_version_id` option.
Client can assert that the record does not exist by passing [oxia.EXPECTED_RECORD_DOES_NOT_EXIST]
Client can create an ephemeral record with `ephemeral=True`

Parameters
key:`str`	the key to associate with the value
value:`str \| bytes`	the value to associate with the key
partition_key:`str`	the partition key to use (instead of the actual record key)
expected_version_id:`int`	the expected version id of the record to insert. If not specified, the put operation is not conditional.
ephemeral:`bool`	whether the record should be created as ephemeral. Ephemeral records are deleted when the session expires.
sequence_keys_deltas:`list[int]`	a list of sequence keys to be used as deltas for the key. Oxia will create new unique keys atomically adding the sequence key deltas to the key.
secondary_indexes:`dict[str, str]`	a dictionary of secondary indexes to be created for the record.

Returns
`(str, Version)`	(actual_key, version)

Raises
`oxia.ex.InvalidOptions`	if the sequence_keys_deltas option is used with partition_key
`oxia.ex.UnexpectedVersionId`	if the expected version id does not match the current version id of the record

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

perform a scan for existing records with any keys within the specified range.

Note: Oxia uses a custom sorting order that treats `/` characters in special way. Refer to this documentation for the specifics: https://oxia-db.github.io/docs/features/oxia-key-sorting

Parameters
min_key_inclusive:`str`	the minimum key to list from (inclusive).
max_key_exclusive:`str`	the maximum key to list to (exclusive).
partition_key:`str`	if set, the range-scan will be applied to the shard with the specified partition key.
use_index:`str`	if set, the range-scan will be applied to the secondary index with the specified name.

Returns
`Iterator[tuple[str, str, Version]]`	an iterator over the records within the specified range. Each record is a tuple of (key, value, version).

@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) -> (str, str, 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, str, Version]]: (source) ¶

Undocumented

_closed: bool = (source) ¶

Undocumented

_connections = (source) ¶

Undocumented

_service_discovery = (source) ¶

Undocumented

_session_manager = (source) ¶

Undocumented