`EzNoSQLClient`

Important

A client instance manages a connection token and provides context management functionality using __enter__() and __exit__() methods. Please note that only one active connection is supported per client, and all member functions require a valid database connection.

Additional connections can be established as needed by creating multiple EzNoSQLClient instances with different options, or to load balance the workload. Each connection allows for 1024 concurrent read/write requests.

If opting to manage connection tokens manually, a client connection should be terminated by using the znsq_close() method

class EzNoSQLClient

The EzNoSQLClient class represents a database connection configuration

__init__(database_name: str, timeout: int = 0, read_only: bool = False, force_update: bool = False, descending_keys: bool = False, enable_auto_commit: bool = True, integrity: int = ReadIntegrity.NRI)

Parameters:

database_name (str) – The primary database name as a data set (e.g., MY.EZNOSQL.DATABASE)
timeout (int, optional) – The duration (in seconds) that a lock request will wait before terminating. The default duration is set to 0 seconds
read_only (bool, optional) – Sets read-only access and fails all update (write/replace/delete) requests. The default is set to False
force_update – Sets force write access and ignores duplicate key warnings. The default is set to False
descending_keys (bool, optional) – Sets descending sequential access when retrieving documents via primary index. The default is set to False
enable_auto_commit (bool, optional) – Sets automatic transaction commits after each update (write/replace/delete) or a CRE enabled request. The default is set to True
integrity (int, optional) – The integrity value specifies whether shared locks will be obtained, and the duration the lock will be held in seconds. The default is set to NRI

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)

__enter__()

Opens a runtime context for an EzNoSQLClient connection token

Returns:: self
Return type:: EzNoSQLClient

__exit__(exception_type, exception_value, traceback): Closes a runtime context for an EzNoSQLClient connection token upon execution of a code block

znsq_open() → None

Opens a new connection to the EzNoSQL database

Invoking EzNoSQLClient using a with statement establishes a runtime context to handle the entry and exit for connection resource management

Note

If managing a connection manually, the resource should be explicitly deallocated when it is no longer needed

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

znsq_close() → None

Closes an open connection to the EzNoSQL database

Invoking EzNoSQLClient using a with statement establishes a runtime context to handle the entry and exit for connection resource management

Raises:: EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_report_stats(output_dict: bool = False) → str | dict

Retrieves usage and configuration details from the active connection.

Generates a JSON document containing usage statistics for the primary index as well as all the secondary indices associated with the primary data set. The API also provides the configuration details for the EzNoSQLClient instance

Parameters:

output_dict (bool, optional) – Sets the return type from JSON string to a dictionary. The default is set to False

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

Returns:

A JSON document or dictionary containing the requested connection attributes and usage statistics

Return type:

str | dict

znsq_commit() → None

Issues a commit to end the current transaction queue and release document level locks

The request only applies to recoverable databases (i.e., a database defined with UNDO or ALL attributes)

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

znsq_set_autocommit(enable_autocommit: bool) → None

Enables or disables automatic transaction commits after each update (write/replace/delete) or a CRE enabled request

The request only applies to recoverable databases (i.e., a database defined with UNDO or ALL attributes)

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

znsq_abort() → None

Issues an abort to end the current transaction queue, restore updated documents to their original versions prior to the start of the transaction, and release all document level locks.

The request only applies to recoverable databases (i.e., a database defined with UNDO or ALL attributes)

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

znsq_write(document: str | dict, key: str = '"znsq_id"') → tuple[int, bool, str | None]

Inserts a document into the EzNoSQL database

Parameters:

document (str | dict) – The document to be written into the database. Note that using a dictionary datatype may incur conversion overhead for very large or multi-level nested documents
key (str, optional) – The primary or alternate key. The default is set to the reserved key "znsq_id" used in autogenerated key databases

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected
ValueError – If the key argument is ill-formatted

Returns:

A tuple containing a return code, the result of the request, and a key-value (if writing to an autogenerated database)

Return type:

tuple[int, bool, str | None]

znsq_delete(key_value: str, key: str = '"znsq_id"') → tuple[int, bool]

Deletes a document in the EzNoSQL database

Parameters:

key_value (str) – The value associated with the primary or secondary index key
key (str) – The primary or alternate key. The default is set to the reserved key "znsq_id" used in autogenerated key databases

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
ValueError – Raises a RuntimeError if an invalid connection token is detected
RuntimeError – Raises a RuntimeError if an invalid connection token is detected

Returns:

A tuple containing a return code and the result of the request. The result will return False if a duplicate key (for non-unique index) is detected or if no document was found for the provided key-value

Return type:

tuple[int, bool]

znsq_replace(updated_document: str | dict, key_value: str, key: str = '"znsq_id"') → tuple[int, bool]

Replaces a document in the EzNoSQL database

Parameters:

updated_document (str | dict) – The updated/replacement document. The new document may contain updated and/or new key-value pairs; however, it must not modify the original document’s primary index key-value
key_value (str) – The value associated with the primary or secondary index key
key (str) – The primary or alternate key. The default is set to the reserved key "znsq_id" used in autogenerated key databases

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected
ValueError – If the key argument is ill-formatted

Returns:

A tuple containing a return code and the result of the request. The result will return False if a duplicate key (for non-unique index) is detected or if no document was found for the specified key-value

Return type:

tuple[int, bool]

znsq_read(key_value: str, key: str = '"znsq_id"', update_on_read: bool = False) → tuple[int, str | None, ResultSet | None]

Retrieves a document in the EzNoSQL database

Parameters:

key_value (str) – The value associated with the primary or secondary index key.
key (str) – The primary or alternate key. The default is set to the reserved key "znsq_id" used in autogenerated key databases
update_on_read (bool, optional) – Enable a direct update upon retrieving the document with an exclusive lock

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected
ValueError – If the key argument is ill-formatted

Returns:

A tuple containing a return code, the retrieved document (if found), and a ResultSet (if update_on_read=True).

Return type:

tuple[int, str | None, ResultSet | None]

znsq_position(key_value: str = None, key: str = '"znsq_id"', exact_search: bool = False) → tuple[int, ResultSet | None]

Positions to a key in the EzNoSQL database

Note

If managing a ResultSet manually, the resource should be explicitly deallocated when it is no longer needed

Parameters:

key_value (str, optional) – The value associated with the primary or alternate key. A key value of None positions to either the top or bottom of the database according to the orientation set by the EzNoSQLClient.descending_keys attribute
key (str) – The primary or alternate key. Omitting a value will default to the reserved key "znsq_id" for autogenerated key databases
exact_search (bool, optional) – Enables exact key-value search, otherwise the key-value matches on a generic value (greater-than-or-equal-to), defaults to False

Raises:

EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
RuntimeError – Raises a RuntimeError if an invalid connection token is detected
ValueError – If the key argument is ill-formatted

Returns:

A tuple containing a return code and a ResultSet instance positioned to the key-value pair provided (if found)

Return type:

tuple[int, ResultSet | None]