NoSQLClient

NoSQLClient

NoSQLClient is provides access to Oracle NoSQL Database tables. Methods of this class are used to create and manage tables and indexes, and to read and write data. All operations are performed asynchronously.

Each method returns a Promise object that will resolve to the result of the operation if successful, or reject with an error upon failure. To handle results and errors, you may use promise chains with .then.catch or async functions with await. The result of operation is a JavaScript object with properties specific to each operation and is documented for each method below. If any error has occurred, the promise will reject with NoSQLError or one of its subclasses.

You instantiate NoSQLClient by providing connection and credential information, either in the form of a configuration object of type Config or a path to a file that holds Config information. Some parameters, such as the service endpoint or region, are required. Other parameters are optional and need not be specified in the Config. Default values are used for optional parameters.

Note that it is possible to create NoSQLClient instance without providing configuration if all of the following are true:

  • You are using NoSQLClient with the Cloud Service.
  • You store your credentials and region identifier in an OCI configuration file with the default file path and default profile name. See IAMConfig for more information.
  • You use defaults for all other configuration properties.

Each method of NoSQLClient also takes an optional opt parameter which contains options specific to a particular operation. Some of these options may be the same as those specified by Config and will override the Config values for this operation. The method description describes which options are pertinent for that operation. If an options is not specified in the opt parameter and is also not present in Config, the driver will use default values.

In general, same methods and options are applicable to both Oracle NoSQL Database Cloud Service and On-Premise Oracle NoSQL Database. However, some methods, options and result types may be specific to particular ServiceType, which is specified in their documentation.

For cloud service only: for each method you may provide opt.compartment which specifies the compartment of the given table (or compartment used to perform given operation). If not set in options or initial config (see Config#compartment), the root compartment of the tenancy is assumed. The compartment is a string that may be either the id (OCID) of the compartment or a compartment name. Both are acceptable. If a name is used it can be either the name of a top-level compartment, or for nested compartments, it should be a compartment path to the nested compartment that does not include the root compartment name (tenant), e.g. compartmentA.compartmentB.compartmentC

Alternatively, instead of setting opt.compartment you may prefix the table name with its compartment name (for top-level compartments) or compartment path (for nested compartments), e.g. compartmentA.compartmentB.compartmentC:myTable. Note that the table name cannot be prefixed with compartment id. Prefixing the table with compartment name/path takes precendence over other methods of specifying the compartment.

Constructor

new NoSQLClient(configopt)

Source:
Tutorials:
See:
Constructs an instance of NoSQLClient. This function is synchronous.
Example
// Using NoSQLClient with async-await

const NoSQLClient = require('oracle-nosqldb').NoSQLClient;

async function test() {
     let client;
     try {
         client = new NoSQLClient('config.json');
         let res = await client.tableDDL(
             'CREATE TABLE foo(id INTEGER, name STRING, PRIMARY KEY(id))',
             {
                 tableLimits: {
                     readUnits: 100,
                     writeUnits: 100,
                     storageGB: 50
                 }
             }
         );
         console.log('Table: %s, state: %s', res.tableName,
             res.tableState);
         await client.forCompletion(res);
         res = await client.put('foo', { id: 1, name: 'test' });
         res = await client.get('foo', { id: 1 });
         console.log(res.row);
         //..........
     } catch(err) {
         //handle errors
     } finally {
         if (client) {
             client.close();
         }
     }
}
Parameters:
Name Type Attributes Description
config string | Config | null <optional>
Configuration for NoSQL client. May be either a string indicating the file path to a configuration file, or a Config object. If a file path is supplied, the path can be absolute or relative to the current directory of the application. The file should contain the Config object and can be either JSON or JavaScript (in the latter case it's module.exports should be set to the Config object). Note that you may pass null or omit this parameter (use no-argument constructor) if using the cloud service with the default OCI configuration file that contains credentials and region identifier, as described above
Fires:
Throws:
if the configuration is missing required properties or contains invalid property values
Type
NoSQLArgumentError

Members

(static) version

Source:
Returns the version of the driver.

Methods

(async) adminDDL(stmt, optopt) → {Promise}

Source:
See:
On-premise only.

Performs an administrative operation on the system. The operations allowed are defined by Data Definition Language (DDL) portion of the query language that do not affect a specific table. For table-specific DLL operations use NoSQLClient#tableDDL.

Examples of statements 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

Note that these are potentially long-running operations, so the result returned by this API does not imply operation completion. The caller should use the NoSQLClient#adminStatus method to check the status of the operation or NoSQLClient#forCompletion to asynchronously wait for the operation completion.

Alternatively, if opt.complete is set to true, this API will complete (i.e. the returned Promise will resolve) only when the operation is completed. This is equivalent to sequentially executing NoSQLClient#adminDDL and NoSQLClient#forCompletion. In this case, opt.timeout covers the whole time interval until operation completion. Accordingly, if not specified, opt.timeout will default to the sum of Config#ddlTimeout and Config#adminPollTimeout. You may also use opt.delay to specify polling delay (see NoSQLClient#forCompletion).

Note that some of the statements used by admin DDL may contain passwords in which case it is advisable to pass the statement as Buffer so that the memory can be subsequently cleared by the application. The Buffer should contain the statement as UTF-8 encoded string.

Parameters:
Name Type Attributes Description
stmt Buffer | string Statement for the operation as string or Buffer containing UTF-8 encoded string
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#ddlTimeout (or to Config#ddlTimeout + Config#adminPollTimeout if opt.complete is true)
complete boolean <optional>
If set to true, the returned Promise will only resolve when the operation is completed
delay number <optional>
If opt.complete is true, specifies delay between successive polls while waiting for operation completion. Defaults to Config#adminPollDelay. Has no effect if opt.complete is not enabled
Returns:
Promise of AdminResult
Type
Promise

(async) adminStatus(adminResult, optopt) → {Promise}

Source:
See:
On-premise only.

Check the status of the operation performed by NoSQLClient#adminDDL. Returns the status of the operation as AdminResult, that includes operation state and operation output if any.

Parameters:
Name Type Attributes Description
adminResult AdminResult Result returned by NoSQLClient#adminDDL
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
timeout object <optional>
Timeout for the operation in milliseconds, defaults to Config#timeout
Returns:
Promise of AdminResult
Type
Promise

close() → {Promise}

Source:
See:
Releases resources associated with NoSQLClient. This method must be called after NoSQLClient is no longer needed.
Returns:
Promise, which may be resolved if closing the client did not require asynchronous operations. The resolved value is ignored. Currently, the close may need to perform asynchronous operation only when using ServiceType.KVSTORE, otherwise resolved Promise is returned. The Promise should not reject (rather log the error if any), so you only need to await for it if you need to perform an action upon its completion.
Type
Promise

(async) delete(tableName, key, optopt) → {Promise}

Source:
See:
Deletes a row from a table. The row is identified using a primary key value.

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 opt.matchVersion

It is also possible, on failure, to return information about the existing row. The row and its version can be optionally returned as part of DeleteResult if a delete operation fails because of a version mismatch. The existing row information will only be returned if opt.returnExisting is true and opt.matchVersion is set and the operation fails because the row exists and its version does not match. Use of opt.returnExisting may result in additional consumed read capacity. If the operation is successful there will be no information returned about the previous row.

The information about the result of the delete operation is returned as DeleteResult. Note that the failures to delete if the row doesn't exist or if opt.matchVersion is set and the version did not match are still considered successful as API calls, i.e. they result in DeleteResult and not NoSQLError, see DeleteResult#success. However if delete fails for other reasons, this API call will result in error instead.

Parameters:
Name Type Attributes Description
tableName string Table name
key Key Primary Key of the row
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
returnExisting boolean <optional>
If set to true, existing row and it's version will be returned as part of DeleteResult if delete operation fails because of version mismatch as discussed above
matchVersion Version <optional>
If set, delete only if there is an existing row that matches the primary key and its Version matches the value provided
Returns:
Promise of DeleteResult
Type
Promise

(async) deleteIfVersion(tableName, key, matchVersion, optopt) → {Promise}

Source:
See:
Performs a delete if there is an existing row that matches the primary key and its Version matches the value provided. This API is a shorthand for NoSQLClient#delete with opt.matchVersion specified.
Parameters:
Name Type Attributes Description
tableName string Table name
key Key Primary key, same as in NoSQLClient#delete
matchVersion Version Version to match
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Same as in NoSQLClient#delete
timeout number <optional>
Same as in NoSQLClient#delete
returnExisting boolean <optional>
Same as in NoSQLClient#delete
Returns:
Promise of DeleteResult
Type
Promise

(async) deleteMany(tableName, keys, optopt) → {Promise}

Source:
Executes a sequence of delete 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 single transaction, thus making the operation atomic. This API is a shortcut to NoSQLClient#writeMany with two simplifications:
  • The sequence contains only delete operations.
  • Options are specified only in the opt argument of this API and are same for all delete sub-operations (no per-sub-operation options).
This API may be more more convenient to use than NoSQLClient#writeMany when applicable.
Parameters:
Name Type Attributes Description
tableName string
keys Array.<Key> Array of primary keys to delete, see Key
opt object <optional>
Options object. All options are the same as in NoSQLClient#delete, besides an additional abortOnFail option, see below
Properties
Name Type Attributes Description
abortOnFail boolean <optional>
If set to true, aborts the whole transaction if any of the deletes fails. This is only applicable to failures due non-existence of the row or inability to match opt.matchVersion, see discussion in NoSQLClient#delete. Other failures will result in error
Returns:
Promise of WriteMultipleResult
Type
Promise

(async) deleteRange(tableName, key, optopt) → {Promise}

Source:
See:
Deletes multiple rows from a table residing on the same shard in an atomic operation. A range of rows is specified using a partial primary key plus a field range based on the portion of the key that is not provided. The partial primary key must contain all of the fields that are in the shard key. For example if a table's primary key is <id, timestamp> and the its shard key is the id, it is possible to delete a range of timestamp values for a specific id by providing a key with an id value but no timestamp value and providing a range of timestamp values in the opt.fieldRange. If the field range is not provided, the operation will delete all rows matching the partial key.

The information about the result of this operation will be returned as MultiDeleteResult.

Because this operation can exceed the maximum amount of data modified in a single operation it is possible that it will delete only part of the range of rows and a continuation key will be set in MultiDeleteResult that can be used to continue the operation.

Parameters:
Name Type Attributes Description
tableName string Table name
key Key Partial Primary Key
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
fieldRange FieldRange <optional>
Field range based on columns not provided in partial key. For more details, see FieldRange
maxWriteKB number <optional>
The limit on the total KB write during this operation. This value can only reduce the system defined limit. An attempt to increase the limit beyond the system defined limit will result in error
continuationKey ContinuationKey <optional>
Continuation key returned in MultiDeleteResult from the previous call to this API and can be used to continue this operation. Operations with a continuation key still require the primary key
Returns:
Promise of MultiDeleteResult
Type
Promise

(async) forCompletion(res, optopt) → {Promise}

Source:
See:
Asynchronously waits for DDL operation completion.

DDL operations are operations initiated by NoSQLClient#tableDDL and NoSQLClient#adminDDL (the latter on-premise only). These are potentially long-running operations and the results returned by NoSQLClient#tableDDL or NoSQLClient#adminDDL do not imply operation completion. NoSQLClient#forCompletion takes the result of either operation as an argument and completes (i.e. the returned Promise resolves) when the corresponding operation is completed by the service. This is accomplished by polling the operation state at specified intervals using NoSQLClient#getTable for table DDL operations and NoSQLClient#adminStatus for admin DDL operations.

For table DDL operations initiated by NoSQLClient#tableDDL this method asynchronously waits for state TableState.ACTIVE for all operations except "DROP TABLE", in the latter case asynchronously waiting for TableState.DROPPED.

The result of this method is TableResult or AdminResult representing the state of the operation at the last poll. If the operation fails, this method will result in error (i.e. the returned Promise will reject with error) contaning information about the operation failure.

Note that on operation completion, the passed TableResult or AdminResult is modified in place (to reflect operation completion) in addition to being returned.

As a more convenient way to perform DDL operations to completion, you may pass opt.complete to NoSQLClient#tableDDL or NoSQLClient#adminDDL. In this case, after DDL operation is initiated, these methods will internally use NoSQLClient#forCompletion to await operation completion.

Example
// Using forCompletion
try {
    let res = await client.tableDDL('DROP TABLE.....');
    await client.forCompletion(res);
    res = await client.adminDDL('CREATE NAMESPACE.....');
    await client.forCompletion(res);
} catch(err) {
    // May be caused by client.forCompletion() if long running DDL
    // operation was unsuccessful.
}
Parameters:
Name Type Attributes Description
res TableResult | AdminResult Result of NoSQLClient#tableDDL or NoSQLClient#adminDDL. This result is modified by this method on operation completion.
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout in milliseconds, i.e. how long to keep polling for operation completion. Defaults to Config#tablePollTimeout for table DDL operations or to Config#adminPollTimeout for admin DDL operations
delay number <optional>
Delay in milliseconds between successive polls, determines how often the polls are performed. Defaults to Config#tablePollDelay for table DDL operations or to Config#adminPollDelay for admin DDL operations
Returns:
Promise of TableResult or AdminResult, which is the object passed as first argument and modified to reflect operation completion
Type
Promise

(async) forTableState(tableName, tableState, optopt) → {Promise}

Source:
See:
Waits asynchronously for the table to reach a desired state. This is achieved by polling the table at specified intervals.

This API is used to ensure that the table is ready for data operations after it has been created or altered. It should only be used if the table DDL operation has been performed outside of the current flow of control (e.g. by another application) such that the TableResult of the DDL operation is not available. To wait for completion of the table DDL operation that you issued, use NoSQLClient#forCompletion. This API waits until the table has transitioned from an intermediate state like TableState.CREATING or TableState.UPDATING to a stable state like TableState.ACTIVE, at which point it can be used.

The result of this operation, if successful, is a TableResult that shows the table state from the last poll. The state of TableState.DROPPED is treated specially in that it will be returned as success, even if the table does not exist. Other states will throw an exception if the table is not found.

Parameters:
Name Type Attributes Description
tableName string Table name
tableState TableState Desired table state
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds, i.e. how long to keep polling for desired table state. Defaults to Config#tablePollTimeout
delay number <optional>
Delay in milliseconds between successive polls, determines how often the polls are performed. Defaults to Config#tablePollDelay
Returns:
Promise of TableResult representing result of the last poll
Type
Promise

(async) get(tableName, key, optopt) → {Promise}

Source:
See:
Gets the row associated with a primary key. On success the value of the row is available as property of GetResult. If there are no matching rows, the operation is still successful the row property will be set to null.
Parameters:
Name Type Attributes Description
tableName string Table name
key Key Primary Key of the row
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
consistency Consistency <optional>
Consistency used for the operation. Defaults to Config#Consistency
Returns:
Promise of GetResult
Type
Promise

(async) getIndex(tableName, indexName, optopt) → {Promise}

Source:
See:
Retrieves information about specific index of the table as IndexInfo object.
Parameters:
Name Type Attributes Description
tableName string Table name
indexName string Index name
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
Returns:
Promise of IndexInfo
Type
Promise

(async) getIndexes(tableName, optopt) → {Promise}

Source:
See:
Retrieves information about indexes of the table as array of IndexInfo objects.
Parameters:
Name Type Attributes Description
tableName string Table name
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
indexName string <optional>
Return information only about specific index, same as NoSQLClient#getIndex. If not specified, information on all indexes is returned
Returns:
Promise of IndexInfo[]
Type
Promise

(async) getTable(table, optopt) → {Promise}

Source:
See:
Retrieves static information about a table, including its provisioned througput, capacity and schema, in the form of TableResult. Dynamic information such as usage() is obtained using getTableUsage
Parameters:
Name Type Attributes Description
table string | TableResult Either a table name or a TableResult object that was returned from a call to NoSQLClient#tableDDL. If the latter, error information for the DDL operation will be retrieved, so if the original call failed, this follow-on call will also fail with the same error.
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
Returns:
Promise of TableResult
Type
Promise

(async) getTableUsage(tableName, optopt) → {Promise}

Source:
See:
Note: this method is only supported when using the driver with the Cloud Service. It is not supported when using the driver with On-Premise NoSQL Database (see ServiceType.KVSTORE), in which case it will result in error.

Retrieves dynamic information associated with a table, as returned in TableUsageResult. This information includes a time series of usage snapshots, each indicating data such as read and write throughput, throttling events, etc, as found in TableUsage.

Usage information is collected in time slices and returned in individual usage records. It is possible to return a range of usage records within a given time period. Unless the time period is specified, only the most recent usage record is returned. Usage records are created on a regular basis and maintained for a period of time. Only records for time periods that have completed are returned so that a user never sees changing data for a specific range.

Parameters:
Name Type Attributes Description
tableName string Table name
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
startTime Date | string | number <optional>
Start time for the time period. Can be JavaScript Date, string representing date and time or number of milliseconds since epoch (January 1, 1970, 00:00:00 UTC). For string representation see Date.parse(). If time range is not specified, the most recent complete usage record is returned
endTime Date | string | number <optional>
End time for the time period, represented same as opt.startTime
limit number <optional>
Limit to the number of usage records desired. If not specified or value is 0, there is no limit, but not all usage records may be returned due to size limitations
Returns:
Promise of TableUsageResult
Type
Promise

(async) listNamespaces(opt) → {Promise}

Source:
See:
On-premise only.

Returns the namespaces in the store as an array of strings. If no namespaces are found, empty array is returned.

This operation entails executing admin DDL and waiting for operation completion. Thus you may pass options used by NoSQLClient#adminDDL method.

Parameters:
Name Type Description
opt object Options object. May include all options used by NoSQLClient#adminDDL except opt.complete which is already implied
Returns:
Promise of string[] of namespace names
Type
Promise

(async) listRoles(opt) → {Promise}

Source:
See:
On-premise only.

Returns the roles in the store as an array of strings. If no roles are found, empty array is returned.

This operation entails executing admin DDL and waiting for operation completion. Thus you may pass options used by NoSQLClient#adminDDL method.

Parameters:
Name Type Description
opt object Options object. May include all options used by NoSQLClient#adminDDL except opt.complete which is already implied
Returns:
Promise of string[] of role names
Type
Promise

(async) listTables(optopt) → {Promise}

Source:
See:
Lists tables, returning table names. If further information about a specific table is desired the NoSQLClient#getTable API may be used. If a given identity has access to a large number of tables the list may be paged by using startIndex and limit options. The list is returned as string array in ListTablesResult. Names are returned in alphabetical order to facilitate paging.
Parameters:
Name Type Attributes Description
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information. Only tables belonging to the given compartment (but not its child compartments) will be listed
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
startIndex number <optional>
The index to use to start returning table names. This is related to the ListTablesResult#lastIndex from a previous request and can be used to page table names. If not set, the list starts at index 0
limit number <optional>
The maximum number of table names to return in the operation. If not set or set to 0, there is no limit
namespace string <optional>
On-premise only. If set, list tables from given namespace only, otherwise list all tables for the user.
Returns:
Promise of ListTablesResult
Type
Promise

(async) listUsers(opt) → {Promise}

Source:
See:
On-premise only.

Returns the users in the store as an array of UserInfo. If no users are found, empty array is returned.

This operation entails executing admin DDL and waiting for operation completion. Thus you may pass options used by NoSQLClient#adminDDL method.

Parameters:
Name Type Description
opt object Options object. May include all options used by NoSQLClient#adminDDL except opt.complete which is already implied
Returns:
Promise of UserInfo[] of objects containing information about each user
Type
Promise

(async) prepare(stmt, optopt) → {Promise}

Source:
Prepares a query for execution and reuse. See NoSQLClient#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.

The result of this operation is PreparedStatement. It supports bind variables in queries which can be used to more easily reuse a query by parameterization, see PreparedStatement for details.

Parameters:
Name Type Attributes Description
stmt string Query SQL statement
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
getQueryPlan boolean <optional>
If true, requests a printout of query execution plan to be included in the returned PreparedStatement as PreparedStatement#queryPlan
Returns:
Promise of PreparedStatement
Type
Promise

(async) put(tableName, row, optopt) → {Promise}

Source:
See:
Puts a row into a table. This method creates a new row or overwrites an existing row entirely. The value used for the put 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 nullable or defaulted must be provided or the operation will fail.

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 opt.isAbsent to do a put only if there is no existing row that matches the primary key.
  • Use opt.ifPresent to do a put only if there is an existing row that matches the primary key.
  • Use opt.matchVersion to do a put only if there is an existing row that matches the primary key and its Version matches that provided by opt.matchVersion.
Note that only one of opt.isAbsent, opt.ifPresent or opt.matchVersion options may be specified for given put operation.

It is also possible, on failure, to return information about the existing row. The row, including it's Version can be optionally returned if a put operation fails because of a Version mismatch or if the operation fails because the row already exists. The existing row information will only be returned if opt.returnExisting is true and one of the following occurs:

  • opt.isAbsent is true and the operation fails because the row already exists.
  • opt.matchVersion is used and the operation fails because the row exists and its Version does not match.
The information about the result of the put operation is returned as PutResult. Note that the failure cases discussed above that resulted from inability to satisfy opt.isAbsent, opt.ifPresent or opt.matchVersion options are still considered successful as API calls, i.e. they result in PutResult and not NoSQLError. See PutResult#success. However if put fails for other reasons, this API call will result in error instead.
Parameters:
Name Type Attributes Description
tableName string Table name
row Row Table Row
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
ifAbsent boolean <optional>
If set to true, do put only if there is no existing row that matches the primary key
ifPresent boolean <optional>
If set to true, do put only if there is existing row that matches the primary key
matchVersion Version <optional>
If set, do a put only if there is an existing row that matches the primary key and its Version matches the value provided
returnExisting boolean <optional>
If set to true, existing row and it's version will be returned as part of PutResult if put operation fails as per discussion above
ttl TimeToLive | number <optional>
Sets TimeToLive value, causing the time to live on the row to be set to the specified value on put. This value overrides any default time to live setting on the table
updateTTLToDefault boolean <optional>
If set to true, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the table's default TTL if set. If the table has no default TTL this state has no effect. By default updating an existing row has no effect on its TTL. This option cannot be specified if opt.ttl is specified
exactMatch boolean <optional>
If true the value must be an exact match for the table schema or the operation will fail. An exact match means that there are no required fields missing and that there are no extra, unknown fields. The default behavior is to not require an exact match
identityCacheSize number <optional>
Sets the number of generated identity values that are requested from the server during a put. This takes precedence over the DDL identity CACHE option set during creation of the identity column. Must be positive integer. If not set, the DDL identity CACHE value is used
Returns:
Promise of PutResult
Type
Promise

(async) putIfAbsent(tableName, row, opt) → {Promise}

Source:
See:
Performs a put if there is no existing row that matches the primary key. This API is a shorthand for NoSQLClient#put with opt.ifAbsent set to true.
Parameters:
Name Type Description
tableName string Table name
row Row Row, same as in NoSQLClient#put
opt object Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Same as in NoSQLClient#put
timeout number <optional>
Same as in NoSQLClient#put
returnExisting boolean <optional>
Same as in NoSQLClient#put
ttl TimeToLive | number <optional>
Same as in NoSQLClient#put
exactMatch boolean <optional>
Same as in NoSQLClient#put
identityCacheSize number <optional>
Same as in NoSQLClient#put
Returns:
Promise of PutResult
Type
Promise

(async) putIfPresent(tableName, row, opt) → {Promise}

Source:
See:
Performs a put if there is existing row that matches the primary key. This API is a shorthand for NoSQLClient#put with opt.ifPresent set to true.
Parameters:
Name Type Description
tableName string Table name
row Row Row, same as in NoSQLClient#put
opt object Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Same as in NoSQLClient#put
timeout number <optional>
Same as in NoSQLClient#put
ttl TimeToLive | number <optional>
Same as in NoSQLClient#put
updateTTLToDefault boolean <optional>
Same as in NoSQLClient#put
exactMatch boolean <optional>
Same as in NoSQLClient#put
identityCacheSize number <optional>
Same as in NoSQLClient#put
Returns:
Promise of PutResult
Type
Promise

(async) putIfVersion(tableName, row, matchVersion, opt) → {Promise}

Source:
See:
Performs a put if there is an existing row that matches the primary key and its Version matches the value provided. This API is a shorthand for NoSQLClient#put with opt.matchVersion specified.
Parameters:
Name Type Description
tableName string Table name
row Row Row, same as in NoSQLClient#put
matchVersion Version Version to match
opt object Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Same as in NoSQLClient#put
timeout number <optional>
Same as in NoSQLClient#put
returnExisting boolean <optional>
Same as in NoSQLClient#put
ttl TimeToLive | number <optional>
Same as in NoSQLClient#put
updateTTLToDefault boolean <optional>
Same as in NoSQLClient#put
exactMatch boolean <optional>
Same as in NoSQLClient#put
identityCacheSize number <optional>
Same as in NoSQLClient#put
Returns:
Promise of PutResult
Type
Promise

(async) putMany(tableName, rows, optopt) → {Promise}

Source:
Executes a sequence of put 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 single transaction, thus making the operation atomic. This API is a shortcut to NoSQLClient#writeMany with two simplifications:
  • The sequence contains only put operations.
  • Options are specified only in the opt argument of this API and are same for all put sub operations (no per-sub-operation options).
This API may be more convenient to use than NoSQLClient#writeMany when applicable.
Parameters:
Name Type Attributes Description
tableName string
rows Array.<Row> Array of rows to put, see Row
opt object <optional>
Options object. All options are the same as in NoSQLClient#put, besides an additional abortOnFail option, see below
Properties
Name Type Attributes Description
abortOnFail boolean <optional>
If set to true, aborts the whole transaction if any of the puts fails. This is only applicable to failures due to inability to satisfy opt.ifAbsent, opt.ifPresent or opt.matchVersion options, see discussion in NoSQLClient#put. Other failures will result in error
Returns:
Promise of WriteMultipleResult
Type
Promise

(async) query(stmt, optopt) → {Promise}

Source:
Queries a table based on the query statement.

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

DDL-style queries such as "CREATE TABLE ..." or "DROP TABLE .." are not supported by this API. Those operations must be performed using NoSQLClient#tableDDL.

For performance reasons prepared queries are preferred for queries that may be reused. Prepared queries bypass compilation of the query. They also allow for parameterized queries using bind variables, see NoSQLClient#prepare.

The result of this operation is returned as QueryResult. It contains array of result records and may contain continuation key as QueryResult#continuationKey.

The amount of data read by a single query request is limited by a system default and can be further limited by setting opt.maxReadKB. 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 QueryResult has a continuation key. In addition, number of results returned by the query may be explicitly limited by setting opt.limit. For this reason queries should always operate in a loop, acquiring more results, until the continuation key is null, indicating that the query is done. Inside the loop the continuation key is applied to NoSQLClient#query by setting opt.continuationKey.

Parameters:
Name Type Attributes Description
stmt string | PreparedStatement Query statement, can be either SQL query string or a prepared query represented as PreparedStatement, see NoSQLClient#prepare
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
consistency Consistency <optional>
Consistency used for the operation. Defaults to Config#consistency
limit number <optional>
Sets the limit on number of rows returned by the operation. This allows an operation to return less than the default amount of data
maxReadKB number <optional>
Sets the limit on the total data read during this operation, in KB. This value can only reduce the system defined limit. An attempt to increase the limit beyond the system defined limit will result in error. This limit is independent of read units consumed by the operation
maxWriteKB number <optional>
Sets the limit on the total data written during this operation, in KB. Relevant for update and delete queries. This value can only reduce the system defined limit. An attempt to increase the limit beyond the system defined limit will result in error. This limit is independent of the write units consumed by the operation
maxMemoryMB number <optional>
Maximum amount of memory in megabytes that may be used locally in this query execution for operations such as duplicate elimination (which may be required if using an index on an array or a map) and sorting. Such operations may require significant amount of memory as they need to cache full result set or a large subset of it in locally. If memory consumption exceeds this value, error will result. Default is 1GB. Defaults to Config#maxMemoryMB
continuationKey ContinuationKey <optional>
Continuation key returned in QueryResult from previous call to this API used to continue the query. If there are no more results, continuation key will be null. Note that it is possible that continuation key is not null, but the query has no more results remaining. In this case the next call to NoSQLClient#query will result in QueryResult#rows being empty array and next continuation key being null. This is possible if the previous call to NoSQLClient#query fetched all remaing rows in the result set but was stopped due to the set limitations, including opt.maxReadKB or opt.limit. In this case the server will not look ahead to check if any more results remain
Returns:
Promise of QueryResult
Type
Promise

(async) setTableLimits(tableName, tableLimits, optopt) → {Promise}

Source:
See:
Note: this method is only supported when using the driver with the Cloud Service or Cloud Simulator. When using the driver with On-Premise NoSQL Database (see ServiceType.KVSTORE), this method is a no-op.

Sets new limits of throughput and storage for existing table.

Same considerations as described in NoSQLClient#tableDDL about long-running operations, using NoSQLClient#forCompletion and options opt.complete and opt.delay apply to this API. See NoSQLClient#tableDDL.

Parameters:
Name Type Attributes Description
tableName string Table name
tableLimits TableLimits New table limits for the table
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#ddlTimeout (or to Config#ddlTimeout + Config#tablePollTimeout if opt.complete is true)
complete boolean <optional>
If set to true, the returned Promise will only resolve when the operation is completed and the table state becomes TableState.ACTIVE
delay number <optional>
If opt.complete is true, specifies delay between successive polls while waiting for operation completion. Defaults to Config#tablePollDelay. Has no effect if opt.complete is not enabled
Returns:
Promise of TableResult
Type
Promise

(async) tableDDL(stmt, optopt) → {Promise}

Source:
See:
Executes a DDL operation on a table. The operations allowed are defined by the Data Definition Language (DDL) portion of the query language related to tables such as table creation and drop, index add and drop, and the ability to alter table schema and table limits.

Operations using table DDL statements infer the table name from the statement itself, e.g. "CREATE TABLE mytable(...)". Table creation requires a valid TableLimits object to define the throughput and storage desired for the table. It is an error for TableLimits to be specified with a statement other than create or alter table.

Note that these are potentially long-running operations, so the result returned by this API does not imply operation completion and the table may be in an intermediate state. (see TableState). The caller should use the NoSQLClient#getTable method to check the status of the operation or NoSQLClient#forCompletion to asynchronously wait for the operation completion.

Alternatively, if opt.complete is set to true, this API will complete (i.e. the returned Promise will resolve) only when the operation is completed and the table reaches state TableState.ACTIVE or TableState.DROPPED (if the operation was "DROP TABLE"). This is equivalent to sequentially executing NoSQLClient#tableDDL and NoSQLClient#forCompletion. In this case, opt.timeout covers the whole time interval until operation completion. Accordingly, if not specified, opt.timeout will default to the sum of Config#ddlTimeout and Config#tablePollTimeout. You may also use opt.delay to specify polling delay (see NoSQLClient#forCompletion).

Parameters:
Name Type Attributes Description
stmt string SQL statement
opt object <optional>
Options object, see below
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#ddlTimeout (or to Config#ddlTimeout + Config#tablePollTimeout if opt.complete is true)
tableLimits TableLimits <optional>
Specifies new table limits for a table. See TableLimits. Note that this property is required when creating a table
complete boolean <optional>
If set to true, the returned Promise will only resolve when the operation is completed and the table state becomes TableState.ACTIVE or TableState.DROPPED (if the operation was "DROP TABLE")
delay number <optional>
If opt.complete is true, specifies delay between successive polls while waiting for operation completion. Defaults to Config#tablePollDelay. Has no effect if opt.complete is not enabled
Returns:
Promise of TableResult
Type
Promise

(async) writeMany(tableName, operations, optopt) → {Promise}

Source:
Executes a sequence of put and delete 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, thus making the operation atomic. It is an efficient way to atomically modify multiple related rows.

There are some size-based limitations on this operation:

  • The max number of individual operations (put, delete) in a single call to this API is 50.
  • The total request size is limited to 25MB.
The result of this operation is returned as WriteMultipleResult. On successful completion, it will store array of the execution results of all sub operations. If this operation was aborted because of failure of a sub operation which has opt.abortOnFail set to true, then the index and execution result of the failed sub operation will be stored in WriteMultipleResult (thus the API call in this case is still successful no error results).

Note that in addition to opt argument of this API, each sub operation may have its own opt property as WriteOperation#opt specifying options pertaining to particular put or delete sub operation, see NoSQLClient#put and NoSQLClient#delete (the only exception is timeout which can only be specified for the whole operation in opt argument). Each option value explicitly set in WriteOperation#opt will take precedence over its value in opt argument, otherwise the opt argument can be used to specify options that should be same for all sub operations.

Parameters:
Name Type Attributes Description
tableName string Table name
operations Array.<WriteOperation> Array of WriteOperation objects each representing single put or delete operation, see WriteOperation
opt object <optional>
Options object, specifies options that should be same for all put and delete sub operations (options relevant only to put but not to delete will be ignored for delete operations). Options for specific sub operation, other than timeout may be specified in WriteOperation#opt and will override values specified here. For list of options, see WriteOperation#opt
Properties
Name Type Attributes Description
compartment string <optional>
Cloud service only. Compartment id or name to use for this operation. Defaults to Config#compartment. See Config#compartment for more information
timeout number <optional>
Timeout for the operation in milliseconds. Defaults to Config#timeout
Returns:
Promise of WriteMultipleResult
Type
Promise

Events

consumedCapacity

Source:
NoSQLClient consumedCapacity event. Emitted by NoSQLClient method calls that return ConsumedCapacity as part of their result. These methods include all data manipulation and query methods. This event may be used to calculate relevant statistsics.
Parameters:
Name Type Description
consumedCapacity ConsumedCapacity Capacity consumed by the method call, ConsumedCapacity
op Operation Object describing operation that returned this consumed capacity, see Operation

error

Source:
NoSQLClient error event. Emitted when any NoSQLClient method results in error. This event is not emitted when automatic retries are performed, only when the error is final.

Also mote that this event will not be emitted if it has no listeners, so it is not necessary to subscribe to it.

Parameters:
Name Type Description
err NoSQLError Error of type NoSQLError or one of its subclasses
op Operation Object describing operation that caused the error, see Operation

retryable

Source:
See:
NoSQLClient retryable event. Emitted when error from NoSQLClient operation will result in automatic retry of operation. It will be emitted on each subsequent retry.
Parameters:
Name Type Description
err NoSQLError Error of type NoSQLError or one of its subclasses that caused the retry
op Operation Object describing operation that caused the error, see Operation
numRetries number Number of retries performed so far for this operation, not counting the original API invokation or the retry about to be performed

tableState

Source:
NoSQLClient tableState event. Emitted by NoSQLClient method calls that return table state as part of their result, such as NoSQLClient#getTable, NoSQLClient#tableDDL and NoSQLClient#setTableLimits and also while table is polled waiting for DDL operation completion using NoSQLClient#forCompletion. Can be used to perform actions on a table reaching certain state. Note that this event may be emitted mutliple times even while the table state did not change.
Parameters:
Name Type Description
tableName string Table name
tableState TableState Current table state, see TableState