Welcome to the nosqldb package

All of the classes, constants, and exceptions that are part of the public interface of the Python driver for Oracle NoSQL Database are included here so they can be imported by applications without knowledg of the internal modules implementing the interfaces.

Store Operations

This section contains classes used to configure and manage connections to the proxy server and to the Oracle NoSQL Database Store.

Factory

class nosqldb.Factory

Creates and opens a store connection using the open() method, which returns a Store instance. This instance is used for all store read and write operations.

static open(server_addr, store_config, proxy_config=None)

Opens a connection to the proxy server and, from there, to the Oracle NoSQL Database store. If a properly configured ProxyConfig instance is provided to this method, then this method is capable of automatically starting the proxy server if it is not already running.

When you are done with the Store object returned by this method, close it using the Store.close() method.

For example, to open a connection to a store where the proxy server is already running:

from nosqldb import ConnectionException
from nosqldb import Factory
from nosqldb import StoreConfig

import logging
import sys

store_host_port = "n1.example.org:5000"
proxy_host_port = "localhost:7010"

# configure and open the store
def open_store():
    try:
        kvstoreconfig =
            StoreConfig('MyNoSQLStore', [store_host_port])
        return Factory.open(proxy_host_port, kvstoreconfig)
    except ConnectionException, ce:
        logging.error("Store connection failed.")
        logging.error(ce.message)
        sys.exit(-1)
Parameters:
  • server_addr – A string in the format of hostname:port which represents the location where the proxy server can be found. This parameter is required.
  • store_config – A StoreConfig object. This parameter is required.
  • proxy_config – A ProxyConfig class instance.
Returns:

A Store object if successful, and an exception otherwise.
Raises:

ConnectionException – If the connection was unsuccessful.

ProxyConfig

class nosqldb.ProxyConfig(kvstore_jar=None, kvproxy_jar=None)

Contains information required to start a proxy in the event that a proxy is not currently running. To initialize this class, you can optionally provide paths to kvstore.jar and kvproxy.jar files located on your local drive. By default the system attempts to use the versions of these files bundled with the installation. Specify these if your installation does not have them or you want to use non-default versions.

The location of the jar files provided to this class overrides whatever is specified in your KVSTORE_JAR and KVPROXY_JAR environment variables.

Parameters:
  • kvstore_jar – The location of the kvclient jar. This parameter is required.
  • kvproxy_jar – The location of the proxy jar.
get_iterator_expiration_ms()

Returns the expiration timeout for an iterator in milliseconds.

get_kv_proxy_path_to_jar()

Returns the path to the kvproxy.jar file.

get_kv_store_path_to_jar()

Returns the path to the kvstore.jar file.

get_max_active_requests()

Returns the maximum number of requests that this client can have active for a node in the store.

get_max_concurrent_requests()

Returns the maximum number of active requests allowed between the proxy server and the store.

get_max_iterator_results()

Returns the number of results retrieved by Store.table_iterator() or Store.index_iterator() in a single call to the server.

get_max_open_iterators()

Returns the number for maximum number of active iterators on a connection.

get_max_results_batches()

Returns an integer value representing the maximum number of result batches that can be held in the proxy server process.

get_node_limit_percent()

Returns the maximum number of active requests that can be associated with a node when the request limiting mechanism is active.

get_num_pool_threads()

Returns the number of request handler threads configured for the proxy.

get_request_limit()

Returns the maximum number of requests that this client can have active for a node in the store.

get_request_threshold_percent()

Returns the threshold computed as a percentage of max_active_requests at which requests are limited.

get_request_timeout()

Returns the default request timeout.

get_security_props_file()

Returns the location of the security property configuration file.

get_socket_open_timeout()

Returns the socket open timeout value.

get_socket_read_timeout()

Returns the read timeout associated with sockets used to make client requests.

get_verbose()

Returns a boolean value indicating whether verbose messaging is in use. True means that it is in use.

set_iterator_expiration_ms(ms)

Sets a positive integer representing the expiration timeout for an iterator in milliseconds. The proxy maintains iterator state when an iteration begins. This timeout is used to expire that state if the client does not complete the iteration in a timely manner. The default value is 60000 (60 seconds).

set_kv_proxy_path_to_jar(path_to_jar)

Sets the path to the kvproxy.jar file. Overrides whatever path was provided when this class was initialized, if any. Also overrides any information provided using the KVPROXY_JAR environment variable.

set_kv_store_path_to_jar(path_to_jar)

Sets the path to the kvstore.jar file. Overrides the path that was provided when this class was initialized. Also overrides any information provided using the KVSTORE_JAR environment variable.

set_max_active_requests(requests)

Sets a positive integer representing the maximum number of requests that this client can have active for a node in the KVStore.

set_max_concurrent_requests(max_reqs)

Sets the maximum number of active requests allowed between the proxy server and the store.

set_max_iterator_results(results)

Sets a positive integer representing the number of results retrieved by Store.table_iterator() or Store.index_iterator() in a single call to the server. The default value is 100.

set_max_open_iterators(iterators)

Sets a positive integer representing the maximum number of open iterators in a connection. Because the proxy maintains state for iterators, an excessive number of active (not completed or timed out) iterators can result in memory problems. This method allows specification of a limit. The default value is 10000.

set_max_results_batches(max_res)

Specifies an integer value representing the maximum number of result batches that can be held in the proxy server process.

set_node_limit_percent(percent)

Sets a positive integer representing the maximum number of active requests that can be associated with a node when the request limiting mechanism is active.

set_num_pool_threads(threads)

Sets a positive integer representing the number of threads to use for request handling in the proxy server. The default value is 20.

set_request_limit(limit)

Sets a positive integer representing the maximum number of requests that this client can have active for a node in the store.

set_request_threshold_percent(percent)

Sets a positive integer representing the threshold computed as a percentage of max_active_requests at which requests are limited.

set_request_timeout(timeout)

Sets a positive integer representing the default request timeout value (in milliseconds) for operations performed by this client against the store.

set_security_props_file(f)

Sets the location of the security property configuration file. Note that the security property configuration file is located on the same machine as is running the proxy server.

set_socket_open_timeout(timeout)

Sets a positive integer representing the amount of time (in millseconds) this client will wait when opening a socket to the store.

set_socket_read_timeout(timeout)

Sets a positive integer representing the read timeout (in milliseconds) associated with sockets used to make client requests.

set_verbose(v)

Sets a boolean value indicating whether the client and proxy will issue verbose messaging. Use True if you want verbose messaging. Turning this on can be helpful when troubleshooting problems with connecting to the store.

Store

class nosqldb.Store(client, transport, store_config)

A handle to a store that is running remotely. Use this handle to perform all store read and write operations, as well as to execute grouped sequences of operations. To create an instance of this class, use Factory.open().

close()

Close the connecion with the proxy.

static decode_base_64(data)

Decode the specified Base 64 encoded data.

delete(table, primary_key, write_opts=None)

Deletes a row of data from the named table in the store.

Parameters:
  • table – The name of the table from which the row is to be deleted. This parameter is required.
  • primary_key – A Row object populated with the primary key fields for the row that you want returned. Alternatively, this can be a simple dictionary populated with the primary key fields. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
delete_if_version(table, primary_key, version, write_opts=None)

Deletes a row of data from the named table in the store if and only if the row currently existing in the store has a version that is equal to the version provided here.

Parameters:
  • table – The name of the table from which the row is to be deleted. This parameter is required.
  • primary_key – A Row object populated with the primary key fields for the row that you want returned. Alternatively, this can be a simple dictionary populated with the primary key fields. This parameter is required.
  • version – The version that must match the version currently in the store in order for this delete operation to proceed. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
static encode_base_64(data)

Base 64 encode the specified data.

execute(command)

Asynchronously execute a DDL statement. The method returns immediately without waiting for the statement to run in the store.

Parameters:

command – The DDL statement to be executed. This parameter is required.
Returns:

An ExecutionFuture object.
Raises:
execute_sync(command)

Synchronously execute a DDL statement. The method will only return when the statement has finished.

Parameters:

command – The DDL statement to be executed. This parameter is required.
Returns:

A StatementResult object.
Raises:
  • ExecutionException – If any operation failed when the operation’s ONDB_ABORT_IF_UNSUCCESSFUL key is set to True.
  • FaultException – If the operation cannot be completed for any reason.
  • IllegalArgumentException – If an incorrect argument is used, or a required argument is missing.
  • ProxyException – If communication with the proxy server somehow failed.
execute_updates(ex_list, write_opts=None)

This method provides an efficient and transactional mechanism for executing a sequence of operations associated with tables that share the same shard key portion of their primary keys. The efficiency results from the use of a single network interaction to accomplish the entire sequence of operations.

The operations passed to this method are a list of Operation objects.

All the operations specified are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this method. If the method returns without throwing an exception, then all operations were executed atomically, the transaction was committed, and the returned list contains the result of each operation.

If the transaction is aborted for any reason, an exception is thrown. An abort may occur for two reasons:

  1. An operation or transaction results in an exception that is considered a fault, such as a durability or consistency error, a failure due to message delivery or networking error, and so forth.
  2. An individual operation returns normally but is unsuccessful as defined by the particular operation (that is, a delete operation for a non-existent key) and True was specified for the operation’s ONDB_ABORT_IF_UNSUCCESSFUL key.

Operations are not executed in the sequence they appear in the operations list, but are instead executed in an internally defined sequence that prevents deadlocks. Additionally, if there are two operations for the same key, their relative order of execution is arbitrary; this should be avoided.

Parameters:
  • ex_list – A list of Operation objects. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

An iterable object, each element of which is a OperationResult class object.
Raises:
get(table, primary_key, read_opts=None)

Get the row associated with the primary key.

Parameters:
  • table – The name of the table from which you want to retrieve the row. This parameter is required.
  • primary_key – A Row object populated with the primary key fields for the row that you want returned. Alternatively, this can be a simple dictionary populated with the primary key fields. This parameter is required.
  • read_opts – A ReadOptions class instance.
Returns:

A Row object, or None if the primary key does not exist on the named table.
Raises:
get_execution_future(execution_id)

Returns the ExecutionFuture object encapsulating the operation represented by the provided execution future ID. You can obtain the execution future ID using ExecutionFuture.get_execution_id().

Raises:IllegalArgumentException – If an incorrect argument is used, or a required argument is missing.
get_store_config()

Returns the StoreConfig object used by this handle to the store.

get_version(which_module)

Returns the version associated with a specific module ID. Possible module IDs are:

  • ONDB_JAVA_CLIENT_ID
    Returns the version of the Java client code currently in use.
  • ONDB_PROXY_SERVER_ID
    Returns the version of the proxy server currently in use.
index_iterator(table, index_name, key, key_only, multirow_opts=None, table_iterator_opts=None)

Returns an iterable list of Row objects or keys which match the identified index. For key only iterators the result will contain two columns “primary” - containing the fields of primary key and “secondary” - containing the fields of the secondary index key.

Parameters:
  • table – The name of the table from which you want to retrieve the keys. This parameter is required.
  • index_name – The index you want to use. This parameter is required.
  • key – A dictionary containing the indexed field name and value to be retrieved. All rows matching this search criteria will be returned. This parameter is required.
  • key_only – True if you want to obtain only keys from the iterator. False if you want to complete rows instead. This parameter is required.
  • multirow_opts – A MultiRowOptions instance.
  • table_iterator_opts – A TableIteratorOptions instance.
Returns:

An iterable list of objects matching the partial key. This list is returned lazily, which is to say that the entire list is not returned at once. Rather, list items are retrieved as the list iterator requires them.
Raises:
multi_delete(table, partial_key, multirow_opts=None, write_opts=None)

Delete all rows matching a primary key in an atomic manner. The provided primary key may be a partial key, but it must contain the row’s full shard key.

Parameters:
  • table – The name of the table from which you want to delete the rows. This parameter is required.
  • partial_key – A Row object containing the shard key (which can also be a full or partial primary key). This parameter is required.
  • multirow_opts – A MultiRowOptions instance.
  • write_opts – A WriteOptions instance.
Returns:

The number of rows deleted.
Raises:
multi_get(table, partial_key, key_only, multirow_opts=None, read_opts=None)

Return a list of rows/keys associated with a partial primary key in an atomic manner. Rows or keys are returned in primary key order. The key provided to this method may be a partial key, but it must contain all of the fields defined for the table’s shard key.

Parameters:
  • table – The name of the table from which you want to retrieve the rows or keys. This parameter is required.
  • partial_key – A Row object containing a primary key, which can be a partial key but it must contain the entire shard key. This parameter is required.
  • key_only – A boolean indicating whether you want just keys returned, or the entire row. True if you want just keys. This parameter is required.
  • multirow_opts – A MultiRowOptions instance.
  • read_opts – A ReadOptions instance.
Returns:

A list of rows or keys that matches the provided shard key.
Raises:
multi_key_table_iterator(table, keys, key_only, multirow_opts=None, table_iterator_opts=None)

Returns an iterable list of Row objects or keys which match the provided partial key.

Parameters:
  • table – The name of the table from which you want to retrieve the keys. This parameter is required.
  • keys – A list of Row objects containing keys to use. These keys may be partial but must contain all of the fields in the table’s shard key. This parameter is required.
  • key_only – True if you want to obtain only keys from the iterator. False if you want to retrieve complete rows instead. This parameter is required.
  • multirow_opts – A MultiRowOptions instance.
  • table_iterator_opts – A TableIteratorOptions instance.
Returns:

An iterable list of objects matching the keys in the list. This list is returned lazily, which is to say that the entire list is not returned at once. Rather, list items are retrieved as the list iterator requires them.
Raises:
put(table, row, write_opts=None)

Write a row of data to the table. If the specified row already exists, it is modified. If it does not exist, a new row is added to the table. Both of these default behaviors can be modified through the use of a WriteOptions class instance.

Parameters:
  • table – The name of the table to be written. This parameter is required.
  • row – The row to be written as a Row class instance. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
put_if_absent(table, row, write_opts=None)

Write a row of data to the table if and only if the row is not already present in the table.

Parameters:
  • table – The name of the table to be written. This parameter is required.
  • row – The row to be written as a Row class instance. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
put_if_present(table, row, write_opts=None)

Write a row of data to the table if and only if the row is already present in the table.

Parameters:
  • table – The name of the table to be written. This parameter is required.
  • row – The row to be written as a Row class instance. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
put_if_version(table, row, version, write_opts=None)

Write a row of data to the table if and only if the row currently existing in the store has a version that is equal to the version provided here.

Parameters:
  • table – The name of the table to be written. This parameter is required.
  • row – The row to be written as a Row class instance. This parameter is required.
  • version – The version that must match the version currently in the store in order for this write operation to proceed. This parameter is required.
  • write_opts – A WriteOptions class instance.
Returns:

A tuple, the contents of which differs. If the operation was unsucessful, the tuple contains (False, None). If sucessful then:

  • (True, NONE) if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is NONE.
  • (True, <Row>) where <Row> contains the old row’s data and version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is ALL.
  • (True, <Row>) where <Row> contains just the old row’s data if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VALUE.
  • (True, <Row>) where <Row> contains just the old row’s version if ONDB_RETURN_CHOICE on the WriteOptions provided to this call is VERSION.
Raises:
refresh_tables()

Refresh table changes so that they are available to your client code. Nothing is returned by this method. Use this method if you suspect that table data has been altered. That is, if you suspect there are new tables added to the store, old tables altered in the store, indexes added or altered, and so forth.

Raises:FaultException – If the operation cannot be completed for any reason.
shutdown()

Shutdown the proxy if possible.

table_iterator(table, key, key_only, multirow_opts=None, table_iterator_opts=None)

Returns an iterable list of Row objects or keys which match the provided partial key.

Parameters:
  • table – The name of the table from which you want to retrieve the keys. This parameter is required.
  • key – A Row object containing the partial primary key. This parameter is required.
  • key_only – True if you want to obtain only keys from the iterator. False if you want to retrieve complete rows instead. This parameter is required.
  • multirow_opts – A MultiRowOptions instance.
  • table_iterator_opts – A TableIteratorOptions instance.
Returns:

An iterable list of objects matching the partial key. This list is returned lazily, which is to say that the entire list is not returned at once. Rather, list items are retrieved as the list iterator requires them.
Raises:

StoreConfig

class nosqldb.StoreConfig(store_name, helper_hosts)

Contains information needed to connect to the store. An instance of this class is required by Factory.open().

Initializing this class requires the name of the store to which your code is connecting. The store name was defined when your store was first started. If you are using kvlite instance, the store name is kvlite. For any other store, see the personnel who installed and configured it.

This class also requires a list or tuple of strings with the format host:port, where host is the name of a host where one of your store’s Storage Nodes can be found, and port is the Storage Node’s listening port. At least one host:port pair must be given, and that pair must represent a currently operational Storage Node. If you are using kvlite, then provide only one host:port pair; typically: localhost:5000. For any other store, see the personnel who installed and configured it.

Parameters:
  • store_name – The name of the store to which you are connecting. This parameter is required.
  • helper_hosts – A list or tuple of hostname:port pairs. This parameter is required.
static change_log(level=None, f_name=None)

Turn on logging with the logging level and the file name to log to. level must be one of:

  • NOTSET
  • DEBUG
  • INFO
  • WARNING
  • ERROR
  • CRITICAL
get_consistency()

Returns the Consistency object in use for this store configuration.

get_durability()

Returns the Durability object in use for this store configuration.

get_helper_hosts()

Returns a tuple of strings in the format host:port which represent where your store’s Storage Nodes can be located.

get_max_results()

Returns the default maximum number of results retrieved by Store.table_iterator() or Store.index_iterator() in a single call to the store.

get_read_zones()

Returns the zones in which nodes must be located to be used for read operations, or None if read operations can be performed on nodes in any zone.

get_request_timeout()

Returns the default request timeout.

get_store_name()

Returns the name of the store in use for this configuration.

get_user()

Returns the name of the user authenticating to the store.

get_verify_values()

Returns the relevant parameters for verifying the proxy connection in Thrift format.

set_consistency(consistency)

Sets the Consistency object you want to use as the default consistency policy for this store configuration. This default value can be modified on a per-operation basis. See ReadOptions for details.

set_durability(durability)

Sets the Durability object you want to use as the default durability guarantee for this store configuration. This default value can be modified on a per-operation basis. See WriteOptions for details.

set_helper_hosts(host_list)

Sets a tuple or list of strings in the format host:port which represent where your store’s Storage Nodes can be located. To connect to the store, at least one active Store Node must be identified in the host list.

set_max_results(results)

Sets a positive integer representing the default maximum number of results retrieved by Store.table_iterator() or Store.index_iterator() in a single call to the store. This can modified on a per-operation basis using TableIteratorOptions.

set_read_zones(zone_list)

Sets a tuple or list of zone names in which nodes must be located to be used for read operations.

set_request_timeout(timeout)

Sets a positive integer value representing the request timeout value in milliseconds.

set_store_name(new_name)

Sets the name of the store you want to use for this configuration.

set_user(user)

Sets the name of the user authenticating to the store.

Reads

This section contains classes used to manage read operations performed against the store.

Direction

class nosqldb.Direction(seq=(), **kwargs)

Used with iterator operations to specify the order that keys are returned.

This class functions as a dictionary with just one key, which is mandatory: ONDB_DIRECTION. You may specify one of the following values for this key:

  • ONDB_FORWARD
    Iterate in ascending key order.
  • ONDB_REVERSE
    Iterate in descending key order.
  • ONDB_UNORDERED
    Iterate in no particular key order.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

FieldRange

class nosqldb.FieldRange(seq=(), **kwargs)

Defines a range of values to be used in a table or index iteration, or multi_get operation. A field range is used as the least significant component in a partially specified primary or index key in order to create a value range for an operation that returns multiple rows or keys. The data types supported by a field range are limited to those which are valid for primary keys and/or index keys.

Field ranges are provided to a read operation using a MultiRowOptions class instance.

This class functions as a dictionary with the following keys:

  • ONDB_FIELD
    The name of the field limited by this range.
  • ONDB_START_VALUE
    The lower bound of the range, as a string regardless of the field’s actual type. If no lower bound is to be enforced, do not specify this key. But in that case, ONDB_END_VALUE must be specified.
  • ONDB_START_INCLUSIVE
    Boolean value indicating whether the start value is included in the range. True if it is included.
  • ONDB_END_VALUE
    The upper bound of the range, as a string regardless of the field’s actual type. If no upper bound is to be enforced, do not specify this key. But in that case, ONDB_START_VALUE must be specified.
  • ONDB_END_INCLUSIVE
    Boolean value indicating whether the end value is included in the range. True if it is included.

For example, to specify a range on field id, which is an integer, so that the range is 1 to 3, inclusive:

fr = FieldRange({ ONDB_FIELD : 'id',
                  ONDB_START_VALUE : '1',
                  ONDB_END_VALUE : '3'})

For complex data types, such as a record, use dot notation to specify the field inside the data type. For example, if you have an embedded record, address, and you indexed its field, city, then to specify a field range that includes Chicago to New York, inclusive, use:

fr = FieldRange({ ONDB_FIELD : 'address.city',
                  ONDB_START_VALUE : 'Chicago',
                  ONDB_END_VALUE : 'New York'})
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

MultiRowOptions

class nosqldb.MultiRowOptions(seq=(), **kwargs)

Used to provide various options for read operations in which multiple table rows are returned. This class functions as a dictionary with the following keys:

  • ONDB_FIELD_RANGE
    The FieldRange that limits the rows returned by this operation.
  • ONDB_INCLUDED_TABLES
    List of ancestor or child tables to be included in an operation that returns multiple rows or keys. Note that when specifying child table names, they must be fully-qualified ‘parent.child’ names.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

ReadOptions

class nosqldb.ReadOptions(seq=(), **kwargs)

Used to provide various options for read operations. This class functions as a dictionary with the following keys:

  • ONDB_CONSISTENCY
    The Consistency guarantee that you want to use for this read operation.
  • ONDB_TIMEOUT
    An integer value representing the amount of time in milliseconds that is permitted to elapse before the read operation times out.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Row

class nosqldb.Row(*args, **kwargs)

Represents a table row read from the Oracle NoSQL Database store, or to be written to the store. Row data is represented as a dictionary, with keys representing row field names, and values as the respective row value.

This class also provides several methods related to table name and version management.

get_expiration()

Returns the expiration time of the row. A zero value indicates that the row does not expire. If the row does not have a valid expiration time, an exception is thrown.

get_table_name()

Returns the name of the table to which the row belongs.

get_timetolive()

Returns the time to live (TTL) value for this row or null if it has not been set by a call to set_timetolive().

get_version()

Returns a bytearray representing the row version information. Every time a table row is modified in the store, a new version is automatically assigned to it.

set_expiration(expiration)

Sets expiration time on output. This is used internally by methods that create Row instances retrieved from the server. This method is not used for input.

set_table_name(table_name)

Sets the table name to which the row belongs.

set_timetolive(ttl)

Sets a time to live (TTL) value for the row to be used when the row is inserted into a store.

set_version(version)

Sets the table row version.

split_key_pair()

Returns a tuple that contains the primary key and the secondary index key. This method will only work for results from a key-only index iterator. If called from a different type of result it raises IllegalArgumentException.

ResultIterator

class nosqldb.ResultIterator(itId, batch, hasmore, client)

Provides iteration over a list of results returned by Store.table_iterator and Store.index_iterator. This iterator consumes blocks of data from the store on demand (by default, 100 results for each internal retrieval from the store). In this way, this iterator can potentially save memory over a blind bulk retrieval of an entire result set.

Iterate over the result set through the use of a simple for loop, or by calling the next() method.

If you want to abort the iteration, you must manually call the close() method.

close()

Close the iterator regardless of whether the iterator was exhausted.

next()

Returns the next Row in the result set, or None.

Raises:StopIteration – when no further results are available in the result set.

TableIteratorOptions

class nosqldb.TableIteratorOptions(seq=(), **kwargs)

Used with store read operations that return iterators. It overrides any default values that might have been specified when the store handle was configured.

This class functions as dictionary with the following keys:

  • ONDB_DIRECTION
    The value specified for this key must be a Direction class instance.
  • ONDB_MAX_RESULTS
    Specifies an integer value representing the maximum number of results batches that can be held in the NoSQL Database client process.
  • ONDB_READ_OPTIONS
    The value specified for this key must be a ReadOptions class instance.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Consistency Guarantees

This section contains classes used to define consistency guarantees that are applied to read operations.

Consistency

class nosqldb.Consistency(seq=(), **kwargs)

Used to provide consistency guarantees for read operations.

In general, read operations may be serviced either at a master or replica node. When serviced at the master node, consistency is always absolute. If absolute consistency is required, ABSOLUTE may be specified to force the operation to be serviced at the master. For other types of consistency, when the operation is serviced at a replica node, the transaction will not begin until the consistency policy is satisfied.

The consistency is specified as an argument to all read operations, for example, Store.get().

This class functions as a dictionary with the following keys. NOTE: Only one of the following keys may be used at any given time for this class:

The following convenience constants are also available:

NONE_REQUIRED =
    Consistency({ONDB_SIMPLE_CONSISTENCY: ONDB_NONE_REQUIRED})
ABSOLUTE = Consistency({ONDB_SIMPLE_CONSISTENCY: ONDB_ABSOLUTE})
NONE_REQUIRED_NO_MASTER = Consistency({
    ONDB_SIMPLE_CONSISTENCY: ONDB_NONE_REQUIRED_NO_MASTER})
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

SimpleConsistency

class nosqldb.SimpleConsistency(seq=(), **kwargs)

Used to specify a simple consistency guarantee. This class functions as a dictionary with just one key: ONDB_SIMPLE_CONSISTENCY. This key may have one of the following values:

  • ONDB_ABSOLUTE
    Requires that a transaction be serviced on the master so that consistency is absolute.
  • ONDB_NONE_REQUIRED
    Lets a transaction on a replica using this policy proceed regardless of the state of the replica relative to the master.
  • ONDB_NONE_REQUIRED_NO_MASTER
    Requires that a read operation be serviced on a replica; never the master.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

TimeConsistency

class nosqldb.TimeConsistency(seq=(), **kwargs)

A consistency policy which describes the amount of time the replica is allowed to lag the master. The application can use this policy to ensure that the replica node sees all transactions that were committed on the master before the lag interval.

Effective use of this policy requires that the clocks on the master and replica are synchronized by using a protocol like NTP.

This class functions as a dictionary with the following keys:

  • ONDB_PERMISSIBLE_LAG

    A long value representing the total number of milliseconds the replica is allowed to lag the master when initiating a transaction.

  • ONDB_TIMEOUT

    A long value representing how long a replica may wait for the desired consistency to be achieved before giving up.

    All KVStore read operations support a consistency specification, as well as a separate operation timeout. The KVStore client driver implements a read operation by choosing a node (usually a replica) from the proper replication group, and sending it a request. If the replica cannot guarantee the desired consistency within the consistency timeout, it replies to the request with a failure indication. If there is still time remaining within the operation timeout, the client driver picks another node and tries the request again (transparent to the application).

    It makes sense to think of the operation timeout as the maximum amount of time the application is willing to wait for the operation to complete. The consistency timeout is like a performance hint to the implementation, suggesting that it can generally expect that a healthy replica usually should be able to become consistent within the given amount of time, and that if it does not, then it is probably more likely worth the overhead of abandoning the request attempt and retrying with a different replica. Note that for the consistency timeout to be meaningful it must be smaller than the operation timeout.

    Choosing a value for the operation timeout depends on the needs of the application. Finding a good consistency timeout value is more likely to depend on observations made of real system performance.

validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

VersionConsistency

class nosqldb.VersionConsistency(seq=(), **kwargs)

A consistency policy which ensures that the environment on a replica node is at least as current as denoted by the specified version byte array.

The specified version represents a point in the serialized transaction schedule created by the master. In other words, the version is like a bookmark, representing a particular transaction commit in the replication stream. The replica ensures that the commit identified by the version has been executed before allowing the transaction on the replica to proceed.

For example, suppose the application is a web application. Each request to the web server consists of an update operation followed by read operations (say from the same client). The read operations naturally expect to see the data from the updates executed by the same request. However, the read operations might have been routed to a replica node that did not execute the update.

In such a case, the update request would generate a version byte array, which would be resubmitted by the browser, and then passed with the subsequent read requests to the store. The read request may be directed by the store’s load balancer to any one of the available replicas. If the replica servicing the request is already current (with respect to the version token), it will immediately execute the transaction and satisfy the request. If not, the transaction will stall until the replica replay has caught up and the change is available at that node.

This class functions as a dictionary with the following keys:

  • ONDB_VERSION

    A byte array representing the version that must be matched in order for the consistency guarantee to be met.

  • ONDB_TIMEOUT

    A long value representing how long a replica may wait for the desired consistency to be achieved before giving up.

    All KVStore read operations support a consistency specification, as well as a separate operation timeout. The KVStore client driver implements a read operation by choosing a node (usually a replica) from the proper replication group, and sending it a request. If the replica cannot guarantee the desired consistency within the consistency timeout, it replies to the request with a failure indication. If there is still time remaining within the operation timeout, the client driver picks another node and tries the request again (transparent to the application).

    It makes sense to think of the operation timeout as the maximum amount of time the application is willing to wait for the operation to complete. The consistency timeout is like a performance hint to the implementation, suggesting that it can generally expect that a healthy replica usually should be able to become consistent within the given amount of time, and that if it does not, then it is probably more likely worth the overhead of abandoning the request attempt and retrying with a different replica. Note that for the consistency timeout to be meaningful it must be smaller than the operation timeout.

    Choosing a value for the operation timeout depends on the needs of the application. Finding a good consistency timeout value is more likely to depend on observations made of real system performance.

validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Writes

This section contains classes used to manage write operations performed against the store.

ExecutionFuture

class nosqldb.ExecutionFuture(statement_res, execution_id, client)

Provides a handle to a DDL statement that has been issued asynchronously and is currently being processed by the kvstore. This class provides a way to check on the interim status of the DDL operation, wait for the operation completion, or cancel the operation.

This class is instantiated by Store.execute() and Store.get_execution_future().

If you want to cancel the DDL statement before it has completed, use Store.execution_future_cancel().

cancel(may_interrupt_if_running=None)

Attempts to cancel the asynchronous execution of a DDL statement that was started using execute().

Cancel a DDL operation executed with Store.execute() then return a boolean result indicating if the operation was successful.

Parameters:

may_interrupt_if_running – Boolean indicating whether the operation can be interrupted if is currently in progress.
Returns:

True if the operation was cancelled and passed to FAILED state. Otherwise, False if the operation could not be cancelled, most probably because the operation completed before the DDL statement was executed.
Raises:
get(timeout=None)

This method does not return (blocks) until the DDL statement encapsulated by this class finishes.

Parameters:

timeout – The amount of time in milliseconds you are willing to wait for the statement to complete. If this timeout value is reached, this method throw TimeoutException.
Raises:
  • FaultException – If the operation cannot be completed for any reason.
  • IllegalArgumentException – If an incorrect argument is used, or a required argument is missing.
  • TimeoutException – If the timeout value specified to this method is reached.
  • ExecutionException – If the execution of this instruction failed for any reason in the server.
  • InterruptedException – If the operation was interrupted for any reason.
  • ProxyException – If communication with the proxy server somehow failed.
get_execution_id()

Returns the unique id associated with this execution future.

get_statement()

Returns the DDL statement encapsulated by this class.

get_statement_result()

Returns the StatementResult object representing this execution future.

update_status()

Updates the current status of the DDL operation encapsulated by this class. You can then retrieve the current status using get_statement_result().

Raises:

Durability

class nosqldb.Durability(seq=(), **kwargs)

Represents a durability guarantee. This class functions as a dictionary with the following keys:

  • ONDB_MASTER_SYNC
    The synchronization policy on the shard’s master server.
  • ONDB_REPLICA_SYNC
    The synchronization policy on the shard’s replicas.
  • ONDB_REPLICA_ACK
    The acknowledgement policy.

For synchronization policies, the allowable values are:

  • ONDB_SP_NO_SYNC
    Write but do not synchronously flush the log on transaction commit.
  • ONDB_SP_SYNC
    Write and synchronously flush the log on transaction commit.
  • ONDB_SP_WRITE_NO_SYNC
    Do not write or synchronously flush the log on transaction commit.

For the acknowledgment policy, the allowable values are:

  • ONDB_AP_ALL
    All replicas must acknowledge that they have committed the transaction.
  • ONDB_AP_NONE
    No transaction commit acknowledgments are required and the master will never wait for replica acknowledgments.
  • ONDB_AP_SIMPLE_MAJORITY
    A simple majority of replicas must acknowledge that they have committed the transaction.

The following convenience durability policies are also available. These represent the most commonly used durability policies:

COMMIT_SYNC = Durability({
    ONDB_MASTER_SYNC: ONDB_SP_SYNC,
    ONDB_REPLICA_SYNC: ONDB_SP_NO_SYNC,
    ONDB_REPLICA_ACK: ONDB_AP_SIMPLE_MAJORITY})
COMMIT_NO_SYNC = Durability({
    ONDB_MASTER_SYNC: ONDB_SP_NO_SYNC,
    ONDB_REPLICA_SYNC: ONDB_SP_NO_SYNC,
    ONDB_REPLICA_ACK: ONDB_AP_SIMPLE_MAJORITY})
COMMIT_WRITE_NO_SYNC = Durability({
    ONDB_MASTER_SYNC: ONDB_SP_WRITE_NO_SYNC,
    ONDB_REPLICA_SYNC: ONDB_SP_WRITE_NO_SYNC,
    ONDB_REPLICA_ACK: ONDB_AP_SIMPLE_MAJORITY})
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Result

class nosqldb.Result(string_result=None)

Contains the result status of a StatementResult. It encapsulates a result type and possibly type-dependent data. At this time the only possible result type is ONDB_TYPE_STRING.

get_string_result()

Returns the string result.

get_type()

Returns the type of the result.

StatementResult

class nosqldb.StatementResult(seq=(), **kwargs)

Provides information about the execution and outcome of a table statement. If this object is obtained asynchronously, it can represent information about either a completed or in progress operation. If obtained synchronously, it represents the final status of a finished operation.

This class is obtained using the ExecutionFuture.get_statement_result() method.

This class functions as a dictionary with the following keys:

  • ONDB_INFO
    Contains a textual representation of the statement result.
  • ONDB_INFO_AS_JSON
    Contains a JSON representation of the result’s info.
  • ONDB_ERROR_MESSAGE
    Contains the error message, if any, returned by the operation.
  • ONDB_IS_CANCELLED
    True if the operation was cancelled.
  • ONDB_IS_DONE
    True if the operation was terminated.
  • ONDB_IS_SUCCESSFUL
    True if the operation completed successfully.
  • ONDB_STATEMENT
    Contains the table statement that was executed.
  • ONDB_RESULT
    A Result class instance.
  • ONDB_EXECUTION_ID
    The unique ID assigned to this statement.

WriteOptions

class nosqldb.WriteOptions(seq=(), **kwargs)

Provides options used by store write methods, such as Store.put(). This class functions as a dictionary with the following keys:

  • ONDB_DURABILITY
    A Durability class instance.
  • ONDB_TIMEOUT
    The time, specified in milliseconds, allowed for processing the operation. If zero, the default request timeout is used.
  • ONDB_RETURN_CHOICE
    Identifies what should be returned as the result of the write operation. Possible values are:
    • ‘NONE’
      Do not return a value or a version.
    • ‘ALL’
      Return both the value and the version.
    • ‘VALUE’
      Return the new value only.
    • ‘VERSION’
      Return the version only.
  • ONDB_IF_ABSENT
    Boolean value. If True causes the store write operation to proceed only if the row to be written does not currently exist in the store.
  • ONDB_IF_PRESENT
    Boolean value. If True causes the store write operation to proceed only if the row to be written currently exists in the store.
  • ONDB_IF_VERSION
    Provides a byte array representing a version that must be matched in order for the write operation to proceed. Version byte arrays can be obtained from Row.get_version().
  • ONDB_UPDATE_TTL
    Boolean value, sets whether absolute expiration time will be modified during update. If false and the operation updates a record, the record’ expiration time will not change.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Grouped Table Operations

This sections contains classes used to create and execute a sequence of write operations. A sequence of write operations is an atomic unit: either all the operations succeed or none of them do.

Operation

class nosqldb.Operation(seq=(), **kwargs)

Defines a single operation in a sequence of operations. Instances of this class are added to a list, which is then used with Store.execute_updates().

This class functions as a dictionary with the following keys:

  • ONDB_TABLE_NAME

    The name of the table that the operation is acting upon. This key is required.

  • ONDB_OPERATION

    An OperationType class instance. This key is required.

  • ONDB_ABORT_IF_UNSUCCESSFUL

    Boolean indicating whether the entire operation should be aborted if this operation is unsuccessful. If True the entire operation is aborted upon a non-success result. Default is False.

  • ONDB_ROW

    If the operation type is a put, this must be a dictionary or a Row instance representing the data to be written to the store. If the operation is a delete, this must be a dictionary Row instance representing the primary key of the row to be deleted.

  • ONDB_RETURN_CHOICE

    Specifies whether to return the row value, version, both or neither.

    For best performance, it is important to choose only the properties that are required. The store is optimized to avoid I/O when the requested properties are in cache.

    The value for this key must be one of:

    • ONDB_RC_ALL
      Return both the value and the version.
    • ONDB_RC_NONE
      Do not return the value or the version.
    • ONDB_RC_VALUE
      Return the value only.
    • ONDB_RC_VERSION
      Return the version only.
  • ONDB_VERSION

    A byte array representing the version that must be matched if any of the xxx_IF_VERSION operation types are in use.

validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

OperationResult

class nosqldb.OperationResult(seq=(), **kwargs)

Contains a single result from an sequence of results returned by Store.execute_updates(). This class functions as a dictionary with the following keys:

  • ONDB_CURRENT_ROW_VERSION
    Byte array representing the row’s current version.
  • ONDB_PREVIOUS_ROW
    Row instance representing the row as it existed prior to the execution of the operation.
  • ONDB_PREVIOUS_ROW_VERSION
    Byte array representing the row’s version before the operation was executed.
  • ONDB_WAS_SUCCESSFUL
    Boolean indicating where the operation was successful. True if it was successful.

OperationType

class nosqldb.OperationType(seq=(), **kwargs)

Specifies the type of operation to be performed. This class functions as a dictionary with just one key, which is mandatory: ONDB_OPERATION_TYPE. You may specify one of the following values for this key:

  • DELETE
    A delete operation.
  • DELETE_IF_VERSION
    A delete operation, but only if the version information is satisfied.
  • PUT
    A put operation.
  • PUT_IF_ABSENT
    A put operation, but only if the table row does not currently exist.
  • PUT_IF_PRESENT
    A put operation, but only if the table row currently exists.
  • PUT_IF_VERSION
    A put operation, but only if the version information is satisfied.
validate()

Validates the values provided to this class. If they are not valid, this method raises IllegalArgumentException.

Exceptions

This section contains the exceptions that can be raised by the methods contained in the nosqldb module.

CancellationException

class nosqldb.CancellationException(message)

An error occurred in a DDL statement. One possible reason is that Store.execution_future_get() was cancelled before the DDL statement completed.

ConsistencyException

class nosqldb.ConsistencyException(message)

The Consistency policy for a store read operation could not be met.

ConnectionException

class nosqldb.ConnectionException(message)

The connection to the proxy is not working. The proxy may not be running, the proxy configuration information might not be correct, or (if the proxy is running on a remote host) the network connection between your client and the proxy might be down.

DurabilityException

class nosqldb.DurabilityException(message)

The Durability guarantee could not be met for a store write operation.

ExecutionException

class nosqldb.ExecutionException(message)

An error occurred when asynchronously executing a group of operations, and the operation’s ONDB_ABORT_IF_UNSUCCESSFUL key was set to True.

FaultException

class nosqldb.FaultException(message)

A fault exception was raised in the proxy server.

IllegalArgumentException

class nosqldb.IllegalArgumentException(message)

Exception class that is used when an invalid argument was passed, this could mean that the type is not the expected or the value is not valid for the especific case.

InterruptionException

class nosqldb.InterruptionException(message)

A group of operations were being executed asynchronously, and their operations were interrupted.

OperationExecutionException

class nosqldb.OperationExecutionException(message)

An error occurred when synchronously executing a group of operations, and the operation’s ONDB_ABORT_IF_UNSUCCESSFUL key was set to True.

ProxyException

class nosqldb.ProxyException(message)

The proxy server failed to process a request.

RequestTimeoutException

class nosqldb.RequestTimeoutException(message)

A store operation could not be completed within the time allowed.

TimeoutException

class nosqldb.TimeoutException(message)

A group of operations were being executed asynchronously, and they did not complete in the time allowed.

UnsupportedOperationException

class nosqldb.UnsupportedOperationException(message)

An operation was attempted that is not supported by the proxy.

Indices and tables