NoSQLHandle

class borneo.NoSQLHandle(config)[source]

Bases: object

NoSQLHandle is a handle that can be used to access Oracle NoSQL tables. To create a connection represented by NoSQLHandle, request an instance using NoSQLHandleConfig, which allows an application to specify default values and other configuration information to be used by the handle.

The same interface is available to both users of the Oracle NoSQL Database Cloud Service and the on-premises Oracle NoSQL Database; however, some methods and/or parameters are specific to each environment. The documentation has notes about whether a class, method, or parameter is environment-specific. Unless otherwise noted they are applicable to both environments.

A handle has memory and network resources associated with it. Consequently, the close() method must be invoked to free up the resources when the application is done using the handle. To minimize network activity as well as resource allocation and deallocation overheads, it’s best to avoid repeated creation and closing of handles. For example, creating and closing a handle around each operation, would incur large resource allocation overheads resulting in poor application performance.

A handle permits concurrent operations, so a single handle is sufficient to access tables in a multi-threaded application. The creation of multiple handles incurs additional resource overheads without providing any performance benefit.

With the exception of close() the operations on this interface follow a similar pattern. They accept a Request object containing parameters, both required and optional. They return a Result object containing results. Operation failures throw exceptions. Unique subclasses of Request and Result exist for most operations, containing information specific to the operation. All of these operations result in remote calls across a network.

All Request instances support specification of parameters for the operation as well as the ability to override default parameters which may have been specified in NoSQLHandleConfig, such as request timeouts, etc.

Objects returned by methods of this interface can only be used safely by one thread at a time unless synchronized externally. Request objects are not copied and must not be modified by the application while a method on this interface is using them.

For Error and Exception Handling, on success all methods in this interface return Result objects. Errors are thrown as exceptions. Exceptions that may be retried may succeed on retry. These are instances of RetryableException. Exceptions that may not be retried and if retried, will fail again. Exceptions that may be retried return True for RetryableException.ok_to_retry() while those that may not will return False. Examples of retryable exceptions are those which indicate resource consumption violations such as OperationThrottlingException. Examples of exceptions that should not be retried are IllegalArgumentException, TableNotFoundException, and any other exception indicating a syntactic or semantic error.

Instances of NoSQLHandle are thread-safe and expected to be shared among threads.

Parameters:

config (NoSQLHandleConfig) – an instance of NoSQLHandleConfig.

Raises:

IllegalArgumentException – raises the exception if config is not an instance of NoSQLHandleConfig.

Methods Summary

add_replica(request)

Adds a replica to a table

close()

Close the NoSQLHandle.

delete(request)

Deletes a row from a table.

drop_replica(request)

Drops a replica from a table

do_system_request(statement[, timeout_ms, ...])

A convenience method that performs a SystemRequest and waits for completion of the operation.

do_table_request(request, timeout_ms, ...)

A convenience method that performs a TableRequest and waits for completion of the operation.

get(request)

Gets the row associated with a primary key.

get_client()

get_indexes(request)

Returns information about and index, or indexes on a table.

get_replica_stats(request)

Gets replica statistics information

get_stats_control()

get_table(request)

Gets static information about the specified table including its state, provisioned throughput and capacity and schema.

get_table_usage(request)

Gets dynamic information about the specified table such as the current throughput usage.

list_namespaces()

Returns the namespaces in a store as a list of string.

list_roles()

Returns the roles in a store as a list of string.

list_tables(request)

Lists tables, returning table names.

list_users()

Returns the users in a store as a list of UserInfo.

multi_delete(request)

Deletes multiple rows from a table in an atomic operation.

prepare(request)

Prepares a query for execution and reuse.

put(request)

Puts a row into a table.

query(request)

Queries a table based on the query statement specified in the QueryRequest.

query_iterable(request)

Queries a table based on the query statement specified in the QueryRequest.

system_request(request)

Performs a system operation on the system, such as administrative operations that don't affect a specific table.

system_status(request)

Checks the status of an operation previously performed using system_request().

table_request(request)

Performs an operation on a table.

write_multiple(request)

Executes a sequence of operations associated with a table that share the same shard key portion of their primary keys, all the specified operations are executed within the scope of a single transaction.

Methods Documentation

add_replica(request)[source]

Adds a replica to a table

This operation is implicitly asynchronous. The caller must poll using methods on TableResult to determine when it has completed.

Cloud service only.

Parameters:

request (AddReplicaRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

TableResult

Raises:
Versionadded::

5.4.2

close()[source]

Close the NoSQLHandle.

delete(request)[source]

Deletes a row from a table. The row is identified using a primary key value supplied in DeleteRequest.set_key().

By default a delete operation is unconditional and will succeed if the specified row exists. Delete operations can be made conditional based on whether the Version of an existing row matches that supplied by DeleteRequest.set_match_version().

It is also possible to return information about the existing row. The row, including it’s Version can be optionally returned. The existing row information will only be returned if DeleteRequest.set_return_row() is True and one of the following occurs:

DeleteRequest.set_match_version() is used and the operation fails because the row exists and its version does not match.

DeleteRequest.set_match_version() is not used and the operation succeeds provided that the server supports returning the existing row.

Use of DeleteRequest.set_return_row() may result in additional consumed read capacity.

Parameters:

request (DeleteRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

DeleteResult

Raises:
do_system_request(statement, timeout_ms=30000, poll_interval_ms=1000)[source]

A convenience method that performs a SystemRequest and waits for completion of the operation. This is the same as calling

On-premises only.

system_request() then calling SystemResult.wait_for_completion(). If the operation fails an exception is thrown.

System requests are those related to namespaces and security and are generally independent of specific tables. Examples of statements include

CREATE NAMESPACE mynamespace

CREATE USER some_user IDENTIFIED BY password

CREATE ROLE some_role

GRANT ROLE some_role TO USER some_user

Parameters:

  • statement (str) – the system statement for the operation.

  • timeout_ms (int) – the amount of time to wait for completion, in milliseconds.

  • poll_interval_ms (int) – the polling interval for the wait operation.

Returns:

the result of the system request.

Return type:

SystemResult

Raises:
do_table_request(request, timeout_ms, poll_interval_ms)[source]

A convenience method that performs a TableRequest and waits for completion of the operation. This is the same as calling table_request() then calling TableResult.wait_for_completion(). If the operation fails an exception is thrown. All parameters are required.

Parameters:

  • request (TableRequest) – the TableRequest to perform.

  • timeout_ms (int) – the amount of time to wait for completion, in milliseconds.

  • poll_interval_ms (int) – the polling interval for the wait operation.

Returns:

the result of the table request.

Return type:

TableResult

Raises:
drop_replica(request)[source]

Drops a replica from a table

This operation is implicitly asynchronous. The caller must poll using methods on TableResult to determine when it has completed.

Cloud service only.

Parameters:

request (DropReplicaRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

TableResult

Raises:
Versionadded::

5.4.2

get(request)[source]

Gets the row associated with a primary key. On success the value of the row is available using the GetResult.get_value() operation. If there are no matching rows that method will return None.

The default consistency used for the operation is Consistency.EVENTUAL unless an explicit value has been set using NoSQLHandleConfig.set_consistency() or GetRequest.set_consistency(). Use of Consistency.ABSOLUTE may affect latency of the operation and may result in additional cost for the operation.

Parameters:

request (GetRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

GetResult

Raises:
get_client()[source]
get_indexes(request)[source]

Returns information about and index, or indexes on a table. If no index name is specified in the GetIndexesRequest, then information on all indexes is returned.

Parameters:

request (GetIndexesRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

GetIndexesResult

Raises:
get_stats_control()[source]
get_replica_stats(request)[source]

Gets replica statistics information

Cloud service only.

Parameters:

request (ReplicaStatsRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

ReplicaStatsResult

Raises:

  • IllegalArgumentException – raises the exception if any of the parameters are invalid or required parameters are missing.

  • TableNotFoundException – raises the exception if the specified table does not exist.

  • NoSQLException – raises the exception if the operation cannot be performed for any other reason.

Versionadded::

5.4.2

get_table(request)[source]

Gets static information about the specified table including its state, provisioned throughput and capacity and schema. Dynamic information such as usage is obtained using get_table_usage(). Throughput, capacity and usage information is only available when using the Cloud Service and will be None or not defined on-premises.

Parameters:

request (GetTableRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

TableResult

Raises:
get_table_usage(request)[source]

Gets dynamic information about the specified table such as the current throughput usage. Usage information is collected in time slices and returned in individual usage records. It is possible to specify a time-based range of usage records using input parameters.

Cloud service only.

Parameters:

request (TableUsageRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

TableUsageResult

Raises:
list_namespaces()[source]

Returns the namespaces in a store as a list of string.

On-premises only.

Returns:

the namespaces, or None if none are found.

Return type:

list(str)

list_roles()[source]

Returns the roles in a store as a list of string.

On-premises only.

Returns:

the list of roles, or None if none are found.

Return type:

list(str)

list_tables(request)[source]

Lists tables, returning table names. If further information about a specific table is desired the get_table() interface may be used. If a given identity has access to a large number of tables the list may be paged using input parameters.

Parameters:

request (ListTablesRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

ListTablesResult

Raises:
list_users()[source]

Returns the users in a store as a list of UserInfo.

On-premises only.

Returns:

the list of users, or None if none are found.

Return type:

list(UserInfo)

multi_delete(request)[source]

Deletes multiple rows from a table in an atomic operation. The key used may be partial but must contain all of the fields that are in the shard key. A range may be specified to delete a range of keys.

Parameters:

request (MultiDeleteRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

MultiDeleteResult

Raises:
prepare(request)[source]

Prepares a query for execution and reuse. See query() for general information and restrictions. It is recommended that prepared queries are used when the same query will run multiple times as execution is much more efficient than starting with a query string every time. The query language and API support query variables to assist with re-use.

Parameters:

request (PrepareRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

PrepareResult

Raises:
put(request)[source]

Puts a row into a table. This method creates a new row or overwrites an existing row entirely. The value used for the put is in the PutRequest object and must contain a complete primary key and all required fields.

It is not possible to put part of a row. Any fields that are not provided will be defaulted, overwriting any existing value. Fields that are not noneable or defaulted must be provided or an exception will be thrown.

By default a put operation is unconditional, but put operations can be conditional based on existence, or not, of a previous value as well as conditional on the Version of the existing value.

Use PutOption.IF_ABSENT to do a put only if there is no existing row that matches the primary key.

Use PutOption.IF_PRESENT to do a put only if there is an existing row that matches the primary key.

Use PutOption.IF_VERSION to do a put only if there is an existing row that matches the primary key and its Version matches that provided.

It is also possible to return information about the existing row. The row, including it’s Version can be optionally returned. The existing row information will only be returned if PutRequest.set_return_row() is True and one of the following occurs:

The PutOption.IF_ABSENT is used and the operation fails because the row already exists.

The PutOption.IF_VERSION is used and the operation fails because the row exists and its version does not match.

The PutOption.IF_PRESENT is used and the operation succeeds providing that the server supports returning the existing row

No option is used and the operation replaces and existing row providing that the server supports returning the existing row

Use of PutRequest.set_return_row() may result in additional consumed read capacity.

Parameters:

request (PutRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

PutResult

Raises:
query(request)[source]

Queries a table based on the query statement specified in the QueryRequest.

Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

Table and system-style queries such as “CREATE TABLE …” or “DROP TABLE …” are not supported by these interfaces. Those operations must be performed using table_request() or system_request() as appropriate.

The amount of data read by a single query request is limited by a system default and can be further limited using QueryRequest.set_max_read_kb(). This limits the amount of data read and not the amount of data returned, which means that a query can return zero results but still have more data to read. This situation is detected by checking if the QueryRequest is done using QueryRequest.is_done(). For this reason queries should always operate in a loop, acquiring more results, until QueryRequest.is_done() returns True, indicating that the query is done.

Parameters:

request (QueryRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

QueryResult

Raises:
query_iterable(request: QueryRequest) → QueryIterableResult[source]

Queries a table based on the query statement specified in the QueryRequest.

Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

Table and system-style queries such as “CREATE TABLE …” or “DROP TABLE …” are not supported by these interfaces. Those operations must be performed using table_request() or system_request() as appropriate.

The amount of data read by a single query request is limited by a system default and can be further limited using QueryRequest.set_max_read_kb(). This limits the amount of data read and not the amount of data returned.

Parameters:

request (QueryRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

QueryResult

Raises:
Versionadded::

5.3.6

system_request(request)[source]

Performs a system operation on the system, such as administrative operations that don’t affect a specific table. For table-specific operations use table_request() or do_table_request().

Examples of statements in the SystemRequest passed to this method include:

CREATE NAMESPACE mynamespace

CREATE USER some_user IDENTIFIED BY password

CREATE ROLE some_role

GRANT ROLE some_role TO USER some_user

This operation is implicitly asynchronous. The caller must poll using methods on SystemResult to determine when it has completed.

On-premises only.

Parameters:

request (SystemRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

SystemResult

Raises:
system_status(request)[source]

Checks the status of an operation previously performed using system_request().

On-premises only.

Parameters:

request (SystemStatusRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

SystemResult

Raises:
table_request(request)[source]

Performs an operation on a table. This method is used for creating and dropping tables and indexes as well as altering tables. Only one operation is allowed on a table at any one time.

This operation is implicitly asynchronous. The caller must poll using methods on TableResult to determine when it has completed.

Parameters:

request (TableRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

TableResult

Raises:
write_multiple(request)[source]

Executes a sequence of operations associated with a table that share the same shard key portion of their primary keys, all the specified operations are executed within the scope of a single transaction.

There are some size-based limitations on this operation:

The max number of individual operations (put, delete) in a single WriteMultipleRequest is 50.

The total request size is limited to 25MB.

Parameters:

request (WriteMultipleRequest) – the input parameters for the operation.

Returns:

the result of the operation.

Return type:

WriteMultipleResult

Raises: