`ResultSet`

Important

A ResultSet instance manages a result token and provides context management functionality using __enter__() and __exit__() methods. Please note that only one active result token is supported per instance, and all member functions require a valid database connection and result token. For this reason, the user is discouraged from directly invoking the ResultSet.__init__() constructor. Instead, use the znsq_position() factory method to instantiate a ResultSet.

If opting to manage result tokens manually, positioning should be terminated by using the znsq_close_result() to release a result token.

class ResultSet

The ResultSet class represents a positioning into an EzNoSQL database via a key-value pair. Note that write (write/delete/replace) transactions to a result set must be committed to the database by issuing a znsq_close_result() method before changes are accessible

__enter__()

Opens a runtime context and returns a ResultSet

Returns:: self
Return type:: ResultSet

__exit__(exception_type, exception_value, traceback): Closes a runtime context for a ResultSet

znsq_close_result()

Ends positioning into the EzNoSQL database previously established using the znsq_position() method or znsq_read() with update_on_read=True.

If a ResultSet is invoked using the with statement, the method is automatically called when the execution of the context block is finished

Raises:

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

znsq_next_result(update_on_read: bool = False) → tuple[int, str | None]

Retrieves the current document in a result set

Parameters:

update_on_read (bool, optional) – Enables update access and obtains an exclusive lock for the retrieved document. A subsequent update request is required (e.g., znsq_replace_result(), znsq_delete_result(), and/or meth:~.znsq_close_result) to release the exclusive lock. The default argument 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 client or result token is detected

Returns:

A tuple containing a non-fatal return code, and the retrieved document or None if the positioning reaches the end of the database

Return type:

tuple[int, str | None]

znsq_replace_result(updated_document: str | dict) → tuple[int, bool]

Replaces the current document in a result set

Parameters:

updated_document (str | dict) – The replacement document with updated/additional key-values. Note that the only restriction is that the new document must retain the original’s primary index key-value

Raises:

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

Returns:

A tuple containing a non-fatal return code, and the boolean result of the request

Return type:

tuple[int, bool]

znsq_delete_result() → tuple[int, bool]

Deletes the current document in a result set

Raises:

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

Returns:

A tuple containing a non-fatal return code, and the boolean result of the request

Return type:

tuple[int, bool]