NoSQLClient

// 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();
         }
     }
}

Returns the version of the driver.

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.

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.

Releases resources associated with NoSQLClient. This method must be called after NoSQLClient is no longer needed.

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.

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.

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.

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.

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.

// 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.
}

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.

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.

Retrieves information about specific index of the table as IndexInfo object.

Retrieves information about indexes of the table as array of IndexInfo objects.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

NoSQLClient retryable event. Emitted when error from NoSQLClient operation will result in automatic retry of operation. It will be emitted on each subsequent retry.

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.