Constructs an instance of NoSQLClient. This function is synchronous.
if the configuration is missing required properties or contains invalid property values
Optional config: null | string | ConfigConfiguration 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 its 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
Readonly serviceStatic Readonly captureStatic captureSets or gets the default captureRejection value for all emitters.
Static defaultStatic Readonly errorThis symbol shall be used to install a listener for only monitoring 'error'
events. Listeners installed using this symbol are called before the regular
'error' listeners are called.
Installing a listener using this symbol does not change the behavior once an
'error' event is emitted, therefore the process will still crash if no
regular 'error' listener is installed.
Static Readonly versionThe version of the driver.
Cloud Service only.
Adds replica to a table.
This operation adds replica to a Global Active table. If performed on a regular table (singleton), it will be converted to Global Active table, provided that the sigleton table schema conforms to certain restrictions. For more information, see Global Active Tables in NDCS.
Note that TableLimits for the replica table will default to the table limits for the existing table, however you can override the values of readUnits and writeUnits for the replica by using readUnits and writeUnits. The storage capacity of the replica will always be the same as that of the existing table.
As with tableDDL, the result returned from this API does not imply operation completion. Same considerations as described in tableDDL about long-running operations apply here, including using forCompletion and options complete and delay. See tableDDL.
Note that even after this operation is completed (as described above), the replica table in the receiver region may still be in the process of being initialized with the data from the sender region, during which time the data operations on the replica table will fail with TABLE_NOT_READY.
Promise of TableResult
Table name
Region where to add the replica
Optional opt: AddReplicaOptOptions object, see AddReplicaOpt
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 tableDDL.
Examples of statements passed to this method include:
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 adminStatus method to check the status of the operation or forCompletion to asynchronously wait for the operation completion.
Alternatively, if 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 adminDDL and forCompletion. In this case, timeout covers the whole time interval until operation completion. If not specified, separate default timeouts are used for issuing the DDL operation and waiting for its completion, with values of ddlTimeout and adminPollTimeout correspondingly (the latter defaults to no timeout if adminPollTimeout is not set). You may also use delay to specify polling delay (see 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.
Promise of AdminResult
Statement for the operation as string or Buffer containing UTF-8 encoded string
Optional opt: AdminDDLOptOptions object, see AdminDDLOpt
On-premise only.
Check the status of the operation performed by adminDDL. Returns the status of the operation as AdminResult, that includes operation state and operation output if any.
Promise of AdminResult
Result returned by adminDDL
Optional opt: AdminStatusOptOptions object, AdminStatusOpt
Releases resources associated with NoSQLClient. This method must be called after NoSQLClient is no longer needed.
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 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.
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 RowVersion of an existing row matches that supplied 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 returnExisting is true and matchVersion is set and the operation fails because the row exists and its version does not match. Use of 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 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 success. However if delete fails for other reasons, this API call will result in error instead.
Promise of DeleteResult
Performs a delete if there is an existing row that matches the primary key and its RowVersion matches the value provided. This API is a shorthand for delete with matchVersion specified.
Promise of DeleteResult
Table name
Primary key, same as in delete
RowVersion to match
Optional opt: DeleteIfOptOptions object, see DeleteIfOpt
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 writeMany with the following simplifications:
Promise of WriteMultipleResult
Array of primary keys to delete
Optional opt: DeleteManyOptOptions object, see DeleteManyOpt
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 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.
Promise of MultiDeleteResult
Table name
Partial primary key
Optional opt: MultiDeleteOptOptions object, MultiDeleteOpt
Cloud Service only.
Drops replica from a table.
This operation drops replica from a Global Active table. For more information, see Global Active Tables in NDCS.
As with tableDDL, the result returned from this API does not imply operation completion. Same considerations as described in tableDDL about long-running operations apply here, including using forCompletion and options complete and delay. See tableDDL.
Promise of TableResult
Table name
Region from where to drop the replica
Optional opt: ModifyTableOptOptions object, see ModifyTableOpt
Overload
Asynchronously waits for table DDL operation completion.
Table DDL operations are operations initiated by tableDDL. These are potentially long-running operations and TableResult returned by tableDDL does not imply operation completion. forCompletion takes TableResult 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 getTable until the table state becomes ACTIVE for all operations except "DROP TABLE", in the latter case polling until the table state becomes DROPPED.
The result of this method is TableResult 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 an error) contaning information about the operation failure.
Note that on operation completion, the passed TableResult is modified in place (to reflect operation completion) in addition to being returned.
As a more convenient way to perform table DDL operations to completion, you may pass complete to tableDDL. In this case, after table DDL operation is initiated, tableDDL will use forCompletion to await operation completion.
Using forCompletion with table DDL operation.
try {
let res = await client.tableDDL('DROP TABLE.....');
await client.forCompletion(res);
} catch(err) {
// May be caused by client.forCompletion() if long running table
// DDL operation was unsuccessful.
}
Promise of TableResult, which is the object passed as first argument and modified to reflect operation completion
Result of tableDDL. This result is modified by this method on operation completion
Optional opt: CompletionOptOptions object, see CompletionOpt
Overload
On-premises only. Asynchronously waits for admin DDL operation completion.
Admin DDL operations are operations initiated by adminDDL. These are potentially long-running operations and AdminResult returned by adminDDL does not imply operation completion. forCompletion takes AdminResult 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 adminStatus until the state of operation becomes COMPLETE.
The result of this method is 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 an error) contaning information about the operation failure.
Note that on operation completion, the passed AdminResult is modified in place (to reflect operation completion) in addition to being returned.
As a more convenient way to perform admin DDL operations to completion, you may pass complete to adminDDL. In this case, after DDL operation is initiated, adminDDL will use forCompletion to await operation completion.
Using forCompletion with admin DDL operation.
try {
res = await client.adminDDL('CREATE NAMESPACE.....');
await client.forCompletion(res);
} catch(err) {
// May be caused by client.forCompletion() if long running admin
// DDL operation was unsuccessful.
}
Promise of AdminResult, which is the object passed as first argument and modified to reflect operation completion
Result of adminDDL. This result is modified by this method on operation completion
Optional opt: CompletionOptOptions object, see CompletionOpt
Cloud Service only.
This method waits asynchronously for local table replica to complete its initialization.
After table replica is created, it needs to be initialized by copying the data (if any) from the sender region. During this initialization process, even though the table state of the replica table is ACTIVE, data operations cannot be performed on the replica table.
This method is used to ensure that the replica table is ready for data operations by asynchronously waiting for the initialization process to complete. It works similar to forCompletion by polling the table state at regular intervals until isLocalReplicaInitialized is true.
Note that this operation must be performed in the receiver region where the table replica resides (not in the sender region from where the replica was created), meaning that this NoSQLClient instance must be configured with the receiver region (see region).
Promise of TableResult
Table name
Optional opt: CompletionOptOptions object, see CompletionOpt
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 forCompletion. This API waits until the table has transitioned from an intermediate state like CREATING or UPDATING to a stable state like 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 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.
Promise of TableResult representing result of the last poll
Table name
Desired table state
Optional opt: CompletionOptOptions object, see CompletionOpt
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.
Promise of GetResult
Retrieves information about specific index of the table as IndexInfo object.
Promise of IndexInfo
Table name
Index name
Optional opt: GetIndexOptOptions object, see GetIndexOpt
Retrieves information about indexes of the table as array of IndexInfo objects.
Promise of IndexInfo[]
Table name
Optional opt: GetIndexesOptOptions object, see GetIndexesOpt
Cloud Service only.
Gets replica statistics information.
This operation retrieves stats information for the replicas of a Global Active table. This information includes a time series of replica stats, as found in ReplicaStats. For more information on Global Active tables, see Global Active Tables in NDCS.
It is possible to return a range of stats records or, by default, only the most recent stats records (up to the limit) for each replica if startTime is not specified. Replica stats 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.
By default, this operation returns stats for all replicas as an object keyed by region id of each replica and values being an array of ReplicaStats per replica (see statsRecords). You may limit the result to the stats of only one replica by providing its region.
Because the number of replica stats records can be very large, each call to getReplicaStats returns a limited number of records (the default limit is 1000). You can customize this limit via limit option. You can retrive large number of replica stats records over multiple calls to getReplicaStats by setting startTime on each subsequent call to the value of nextStartTime returned by a previous call.
Promise of ReplicaStatsResult
Table name
Optional opt: ReplicaStatsOptOptions object, see ReplicaStatsOpt.
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
Promise of TableResult
Either a table name or a TableResult object that was returned from a call to 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.
Optional opt: GetTableOptOptions object, see GetTableOpt
Cloud service only. 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 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.
Because the number of table usage records can be very large, you may page the results over multiple calls to getTableUsage using startIndex and limit parameters as shown in the example. However, the recommended way is to call tableUsageIterable and iterate over its result.
Paging over table usage records.
We iterate until the number of returned table usage records becomes less than the limit (and possibly 0), which means that the last partial result has been received.
const now = Date.now();
const opt = {
startTime: now - 3600 * 1000, // last 1 hour
endTime: now,
limit: 100
};
do {
const res = await client.getTableUsage('MyTable', opt);
for(const rec of res.usageRecords) {
console.log(rec);
}
opt.startIndex = res.nextIndex;
} while(res.usageRecords.length === opt.limit);
Promise of TableUsageResult
Table name
Optional opt: TableUsageOptOptions object, see TableUsageOpt.
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 the operation completion.
Promise of string[] of namespace names
Optional opt: AdminListOptOptions object, AdminListOpt
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 the operation completion.
Promise of string[] of role names
Optional opt: AdminListOptOptions object, AdminListOpt
Lists tables, returning table names. If further information about a specific table is desired the 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.
Promise of ListTablesResult
Optional opt: ListTablesOptOptions object, see ListTablesOpt
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 the operation completion.
Promise of UserInfo[] of objects containing information about each user
Optional opt: AdminListOptOptions object, AdminListOpt
Rest ...args: any[]Obtains and caches authorization information in advance of performing database operations.
Built-in authorization providers use with this SDK obtain authorization information such as authorization signature or token and cache it for some time. In some instances, obtaining this information make take some time, especially in cases when a network request to authorization server is required, e.g. when using Cloud Service with Instance Principal (see IAMConfig). By default, this information is obtained on demand when database operation is issued and this may cause timeout errors if the default timeout for database operations is not sufficient to obtain this information. You may call this method to obtain and pre-cache authorization information, so that when database operations are issued, they do not need to spend any extra time on obtaining authorization.
A current use case for this method is when using Cloud Service with Instance Principal, because a network request is required to obtain authorization token (as well additional requests to obtain instance region, instance certificates, instance private key, etc). An alternative solution is to increase operation timeouts to allot enough time to obtain authorzation token when required. However, calling precacheAuth will provide better performance when starting multiple concurrent database operations.
Call this method after creating NoSQLClient instance before performing database operations. Note that after the authorization expires, it will need to be obtained again which make take some time in some cases as described above. However, build-in authoirzation providers used with this SDK are configured to refresh the authorization in background ahead of its expiration so that database operations may use existing authorization while the new one is obtained in the background.
Calling this method is equivalient to calling getAuthorization method of authorization provider which will pre-cache the authorzation in the process, so if using custom AuthorizationProvider that does not cache authorzation, this method will have no effect.
This method does not take explicit timeout, but uses timeouts specified for authorization network requests for given built-in authorization provider. See properties timeout and timeout.
Using precacheAuth on new NoSQLClient instance.
let client;
try {
client = await new NoSQLClient(config).precacheAuth();
.....
} finally {
client?.close();
}
Promise of NoSQLClient of this instance
Prepares a query for execution and reuse. See query for general information and restrictions. It is recommended that prepared queries are used when the same query will run multiple times as execution is much more efficient than starting with a query string every time. The query language and API support query variables to assist with re-use.
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.
Promise of PreparedStatement
Query SQL statement
Optional opt: PrepareOptOptions object, see PrepareOpt.
Rest ...args: any[]Rest ...args: any[]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 RowVersion of the existing value:
It is also possible, on failure, to return information about the existing row. The row, including its RowVersion 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 returnExisting is true and one of the following occurs:
Promise of PutResult
Performs a put if there is no existing row that matches the primary key. This API is a shorthand for put with ifAbsent set to true.
Promise of PutResult
Performs a put if there is existing row that matches the primary key. This API is a shorthand for put with ifPresent set to true.
Promise of PutResult
Performs a put if there is an existing row that matches the primary key and its RowVersion matches the value provided. This API is a shorthand for put with matchVersion specified.
Promise of PutResult
Table name
Row, same as in put
RowVersion to match
Optional opt: PutIfOptOptions object, see PutIfOpt
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 writeMany with the following simplifications:
Promise of WriteMultipleResult
Array of rows to put
Optional opt: PutManyOptOptions object, see PutManyOpt
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 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 prepare.
The result of this operation is returned as QueryResult. It contains array of result records and may contain continuation key as continuationKey.
The amount of data read by a single query request is limited by a system default and can be further limited by setting 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 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 query by setting continuationKey.
The easier way to iterate over query results is by using queryIterable, in which case you do not need to deal with continuaton key.
Promise of QueryResult
Query statement, can be either SQL query string or a prepared query represented as PreparedStatement, see prepare
Optional opt: QueryOptOptions object, see QueryOpt
This API facilitates iteration over query results returned by query by using for-await-of loop. The iteration over query results is necessary because of the limitations on the amount of data read during each query request as described in query. The iteration is asynchronous and each step of the iteration returns a Promise of QueryResult. Using this API is internally equivalent to calling query in a loop and using continuation key returned in QueryResult to continue the query. Thus you do not need to explicitly manage continuation key when using this API.
Note that calling this API by itself does not start the query, the query is started when starting the iteration via for-await-of loop.
The returned iterable cannot be reused for multiple queries. To execute another query, call queryIterable again to create a new iterable.
All other considerations described in query apply when using this API.
Using queryIterable.
try {
const stmt = 'SELECT * from orders';
for await(const res of client.queryIterable(stmt)) {
console.log(`Retrieved ${res.rows.length} rows`);
// Do something with res.rows
}
} catch(err) {
// handle errors
}
Async iterable of QueryResult
Query statement, same as for query
Optional opt: QueryOptOptions object, see <@link QueryOpt>
Optional event: string | symbolRest ...args: any[]Cloud service only. 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 KVSTORE), this method is a no-op.
Sets new limits of throughput and storage for existing table.
Same considerations as described in tableDDL about long-running operations, using forCompletion and options complete and delay apply to this API. See tableDDL.
Promise of TableResult
Table name
New table limits for the table
Optional opt: ModifyTableOptOptions object, see ModifyTableOpt
Cloud service only. 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 KVSTORE), this method is a no-op.
Sets defined and free-form tags on existing table.
See DefinedTags and FreeFormTags for more information on tagging.
Same considerations as described in tableDDL about long-running operations, using forCompletion and options complete and delay apply to this API. See tableDDL.
Promise of TableResult
Table name
Cloud Service only. Defined tags to use for the operation. See DefinedTags. Pass undefined if you wish to set only free-form tags
Optional freeFormTags: FreeFormTagsCloud Service only. Free-form tags to use for the operation. See FreeFormTags. Pass undefined (or omit if not using opt parameter) if you wish to set only defined tags.
Optional opt: ModifyTableOptOptions object, see ModifyTableOpt
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 getTable method to check the status of the operation or forCompletion to asynchronously wait for the operation completion.
Alternatively, if 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 ACTIVE or DROPPED (if the operation was "DROP TABLE"). This is equivalent to sequentially executing tableDDL and forCompletion. In this case, timeout covers the whole time interval until operation completion. If not specified, separate default timeouts are used for issuing the DDL operation and waiting for its completion, with values of ddlTimeout and tablePollTimeout correspondingly (the latter defaults to no timeout if tablePollTimeout is not set). You may also use delay to specify polling delay (see forCompletion).
Promise of TableResult
SQL statement
Optional opt: TableDDLOptOptions object, see TableDDLOpt
Cloud service only. 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 KVSTORE), in which case it will result in error.
Retrieves dynamic information associated with a table, as returned in TableUsageResult.
Use this API when you need to retrieve a large number of table usage records and you wish to page the results rather than returning the whole list at once. The iteration is done by using for-await-of loop. The iteration is asynchronous and each step of the iteration returns a Promise of TableUsageResult. Using this API is equivalent to paging table usage records as shown in the example of getTableUsage.
Note that you must specify a time range (at least one of startTime and endTime for which to return table usage records, otherwise only one (the most recent) table usage record will be returned.
You may optionally specify a limit on the number of table usage records returned in each partial result using limit. If not specified, a default system limit will be used.
Paging table usage records.
const now = Date.now();
const opt = {
startTime: now - 3600 * 1000, // last 1 hour
endTime: now,
limit: 100
};
for await(const res of client.tableUsageIterable('MyTable', opt)) {
for(const rec of res.usageRecords) {
console.log(rec);
}
}
Async iterable of TableUsageResult
5.4
Table name
Optional opt: TableUsageOptOptions object, see TableUsageOpt
Overload
Executes a sequence of put and delete operations associated with a table or tables 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:
Note that in addition to WriteMultipleOpt passed to this API, each sub operation can pass its own put or delete options in WriteOperation Each option explicitly set in WriteOperation will take precedence over its value in WriteMultipleOpt, otherwise WriteMultipleOpt can be used to specify options that should be the same for all sub operations.
It is possible to issue operations for multiple tables as long as these tables have the same shard key. This means that these tables must be part of the same parent/child table hierarchy that has a single ancestor table specifying the shard key (you may include operations for this ancestor table and/or any of its descendants). To issue operations for multiple tables, use the overload of this API without the tableName and specify table per operation as tableName.
Promise of WriteMultipleResult
Table name, if all operations are for a single table. If issuing operations for multiple tables, use the overload without tableName parameter. Specifying tableName parameter together with tableName for any operation will result in error
Array of WriteOperation objects each representing single put or delete operation, see WriteOperation
Optional opt: WriteMultipleOptOptions object, see WriteMultipleOpt
Overload
Array of WriteOperation objects each representing single put or delete operation, see WriteOperation
Optional opt: WriteMultipleOptOptions object, see WriteMultipleOpt
Overload
Array of WriteOperation objects each representing single put or delete operation, see WriteOperation
Optional opt: WriteMultipleOptOptions object, see WriteMultipleOpt
Static listenerStatic onStatic onceGenerated using TypeDoc
NoSQLClient class 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:
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 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.
For events emitted by NoSQLClient, see NoSQLClientEvents.
See
Example
Using NoSQLClient with async-await.