oracle-nosqldb

/*- * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved. * * Licensed under the Universal Permissive License v 1.0 as shown at * https://oss.oracle.com/licenses/upl/ */ import type { EventEmitter } from "events"; import type { Config } from "./config"; import type { TableDDLOpt, ModifyTableOpt, CompletionOpt, GetTableOpt, TableUsageOpt, GetIndexOpt, GetIndexesOpt, ListTablesOpt, GetOpt, PutOpt, PutIfOpt, DeleteOpt, DeleteIfOpt, MultiDeleteOpt, WriteMultipleOpt, PutManyOpt, DeleteManyOpt, PrepareOpt, QueryOpt, AdminDDLOpt, AdminStatusOpt, AdminListOpt, AddReplicaOpt, ReplicaStatsOpt } from "./opt"; import type { TableLimits, TableETag, DefinedTags, FreeFormTags, WriteOperation, RowVersion, Operation } from "./param"; import type { TableResult, TableUsageResult, IndexInfo, ListTablesResult, GetResult, PutResult, DeleteResult, MultiDeleteResult, WriteMultipleResult, QueryResult, AdminResult, UserInfo, ReplicaStats, ReplicaStatsResult } from "./result"; import type { ServiceType, TableState, AdminState } from "./constants"; import type { RowKey, AnyRow, AnyKey } from "./data"; import type { PreparedStatement } from "./stmt"; import type { AuthorizationProvider } from "./auth/config"; import type { IAMConfig } from "./auth/iam/types"; import type { KVStoreAuthConfig } from "./auth/kvstore/types"; import type { NoSQLError } from "./error"; import type { NoSQLClientEvents } from "./events"; import type { Region } from "./region"; /** * Defines NoSQLClient, which is the point of access to the * Oracle NoSQL Database Cloud service. */ /** * 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 {@link 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 * {@link Config} or a path to a file that holds {@link Config} information. * Some parameters, such as the service endpoint or region, are required. * Other parameters are optional and need not be specified in the * {@link Config}. Default values are used for optional parameters. * * Note that it is possible to create {@link NoSQLClient} instance without * providing configuration if all of the following are true: * <ul> * <li>You are using {@link NoSQLClient} with the Cloud Service.</li> * <li>You store your credentials and region identifier in an OCI configuration * file with the default file path and default profile name. See * {@link IAMConfig} for more information.</li> * <li>You use defaults for all other configuration properties.</li> * </ul> * * 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 {@link Config} and will override the {@link 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 * {@link 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 {@link 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 {@link 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. * * For events emitted by {@link NoSQLClient}, see {@link NoSQLClientEvents}. * * @see {@page connect-cloud.md} * @see {@page connect-on-prem.md} * @see {@page tables.md} * * @example * Using {@link NoSQLClient} with async-await. * ```ts * 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(); * } * } * } * ``` */ export class NoSQLClient extends EventEmitter { /** * Constructs an instance of NoSQLClient. This function is synchronous. * @param {string|Config|null} [config] Configuration for NoSQL client. * May be either a string indicating the file path to a configuration * file, or a {@link 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 {@link Config} object * and can be either JSON or JavaScript (in the latter case its * module.exports should be set to the {@link 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 * @throws {NoSQLArgumentError} if the configuration is * missing required properties or contains invalid property values * @see {@link Config} */ constructor(config?: string | Config | null); /** * The version of the driver. */ static readonly version: string; /** * Returns the service type used by this {@link NoSQLClient} instance. * @returns {ServiceType} Service type */ readonly serviceType: ServiceType; /** * Releases resources associated with NoSQLClient. This method must be * called after NoSQLClient is no longer needed. * @returns {Promise} 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 {@link 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. * @see {@link ServiceType} */ close(): Promise<void>; /** * 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 {@link 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 {@link NoSQLClient#precacheAuth} will provide better * performance when starting multiple concurrent database operations. * * Call this method after creating {@link 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 * {@link AuthorizationProvider#getAuthorization} method of authorization * provider which will pre-cache the authorzation in the process, so if * using custom {@link 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 {@link IAMConfig#timeout} and * {@link KVStoreAuthConfig#timeout}. * @example * Using precacheAuth on new NoSQLClient instance. * ```ts * let client; * try { * client = await new NoSQLClient(config).precacheAuth(); * ..... * } finally { * client?.close(); * } * ``` * @async * @returns {Promise} Promise of {@link NoSQLClient} of this instance * @see {@link IAMConfig} * @see {@link KVStoreAuthConfig} * @see {@link AuthorizationProvider} */ precacheAuth(): Promise<NoSQLClient>; /** * 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 {@link 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 {@link * TableState}). The caller should use the {@link NoSQLClient#getTable} * method to check the status of the operation or * {@link NoSQLClient#forCompletion} to asynchronously wait for the * operation completion. * * Alternatively, if {@link TableDDLOpt#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 * {@link TableState.ACTIVE} or {@link TableState.DROPPED} (if the * operation was "DROP TABLE"). This is equivalent to sequentially * executing {@link NoSQLClient#tableDDL} and * {@link NoSQLClient#forCompletion}. In this case, * {@link TableDDLOpt#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 * {@link Config#ddlTimeout} and {@link Config#tablePollTimeout} * correspondingly (the latter defaults to no timeout if * {@link Config#tablePollTimeout} is not set). You may also use * {@link TableDDLOpt#delay} to specify polling delay (see * {@link NoSQLClient#forCompletion}). * @async * @param {string} stmt SQL statement * @param {TableDDLOpt} [opt] Options object, see {@link TableDDLOpt} * @returns {Promise} Promise of {@link TableResult} * @see {@link TableResult} * @see {@link forCompletion} */ tableDDL(stmt: string, opt?: TableDDLOpt): Promise<TableResult>; /** * 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 {@link ServiceType.KVSTORE}), this * method is a no-op. * * Sets new limits of throughput and storage for existing table. * * Same considerations as described in {@link NoSQLClient#tableDDL} about * long-running operations, using {@link NoSQLClient#forCompletion} and * options {@link ModifyTableOpt#complete} and * {@link ModifyTableOpt#delay} apply to this API. * See {@link NoSQLClient#tableDDL}. * @async * @param {string} tableName Table name * @param {TableLimits} tableLimits New table limits for the table * @param {ModifyTableOpt} [opt] Options object, see * {@link ModifyTableOpt} * @returns {Promise} Promise of {@link TableResult} * @see {@link TableResult} * @see {@link NoSQLClient#tableDDL} */ setTableLimits(tableName: string, tableLimits: TableLimits, opt?: ModifyTableOpt): Promise<TableResult>; /** * 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 {@link ServiceType.KVSTORE}), this * method is a no-op. * * Sets defined and free-form tags on existing table. * See {@link DefinedTags} and {@link FreeFormTags} for more * information on tagging. * * Same considerations as described in {@link NoSQLClient#tableDDL} about * long-running operations, using {@link NoSQLClient#forCompletion} and * options {@link ModifyTableOpt#complete} and * {@link ModifyTableOpt#delay} apply to this API. * See {@link NoSQLClient#tableDDL}. * @async * @param {string} tableName Table name * @param {DefinedTags} definedTags Cloud Service only. Defined tags * to use for the operation. See {@link DefinedTags}. Pass * undefined if you wish to set only free-form tags * @param {FreeFormTags} [freeFormTags] Cloud Service only. Free-form * tags to use for the operation. See {@link FreeFormTags}. Pass * undefined (or omit if not using opt parameter) if you * wish to set only defined tags. * @param {ModifyTableOpt} [opt] Options object, see * {@link ModifyTableOpt} * @returns {Promise} Promise of {@link TableResult} * @see {@link DefinedTags} * @see {@link FreeFormTags} * @see {@link TableResult} * @see {@link NoSQLClient.tableDDL} */ setTableTags(tableName: string, definedTags: DefinedTags|undefined, freeFormTags?: FreeFormTags, opt?: ModifyTableOpt): Promise<TableResult>; /** * Retrieves static information about a table, including its * provisioned througput, capacity and schema, in the form of {@link * TableResult}. Dynamic information such as usage() is obtained using * {@link getTableUsage} * @async * @param {string|TableResult} table Either a table name or a * {@link TableResult} object that was returned from a call to * {@link 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. * @param {GetTableOpt} [opt] Options object, see {@link GetTableOpt} * @returns {Promise} Promise of {@link TableResult} * @see {@link NoSQLClient#tableDDL} */ getTable(table: string | TableResult, opt?: GetTableOpt): Promise<TableResult>; /** * @overload * Asynchronously waits for table DDL operation completion. * * Table DDL operations are operations initiated by {@link tableDDL}. * These are potentially long-running operations and {@link TableResult} * returned by {@link tableDDL} does not imply operation completion. * {@link forCompletion} takes {@link TableResult} as an argument and * completes (i.e. the returned {@link !Promise | Promise} resolves) when * the corresponding operation is completed by the service. This is * accomplished by polling the operation state at specified intervals * using {@link getTable} until the table state becomes * {@link TableState.ACTIVE} for all operations except "DROP TABLE", in * the latter case polling until the table state becomes * {@link TableState.DROPPED}. * * The result of this method is {@link 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 {@link !Promise | Promise} will * reject with an error) contaning information about the operation * failure. * * Note that on operation completion, the passed {@link 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 {@link TableDDLOpt#complete} to {@link tableDDL}. In this * case, after table DDL operation is initiated, {@link tableDDL} will use * {@link forCompletion} to await operation completion. * @example * Using forCompletion with table DDL operation. * ```ts * 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. * } * ``` * @async * @param {TableResult} res Result of {@link NoSQLClient#tableDDL}. This * result is modified by this method on operation completion * @param {CompletionOpt} [opt] Options object, see {@link CompletionOpt} * @returns {Promise} Promise of {@link TableResult}, which is the object * passed as first argument and modified to reflect operation completion * @see {@link NoSQLClient#tableDDL} * @see {@link NoSQLClient#getTable} * @see {@link TableResult} */ forCompletion(res: TableResult, opt?: CompletionOpt): Promise<TableResult>; /** * @overload * On-premises only. * Asynchronously waits for admin DDL operation completion. * * Admin DDL operations are operations initiated by {@link adminDDL}. * These are potentially long-running operations and {@link AdminResult} * returned by {@link adminDDL} does not imply operation completion. * {@link forCompletion} takes {@link AdminResult} as an argument * and completes (i.e. the returned {@link !Promise | Promise} resolves) * when the corresponding operation is completed by the service. This is * accomplished by polling the operation state at specified intervals * using {@link adminStatus} until the state of operation becomes * {@link AdminState.COMPLETE}. * * The result of this method is {@link 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 {@link !Promise | Promise} will * reject with an error) contaning information about the operation * failure. * * Note that on operation completion, the passed {@link 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 {@link AdminDDLOpt#complete} to {@link adminDDL}. In this * case, after DDL operation is initiated, {@link adminDDL} will use * {@link forCompletion} to await operation completion. * @example * Using forCompletion with admin DDL operation. * ```ts * 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. * } * ``` * @async * @param {AdminResult} res Result of {@link NoSQLClient#adminDDL}. This * result is modified by this method on operation completion * @param {CompletionOpt} [opt] Options object, see {@link CompletionOpt} * @returns {Promise} Promise of {@link AdminResult}, which is the object * passed as first argument and modified to reflect operation completion * @see {@link NoSQLClient#adminDDL} * @see {@link NoSQLClient#adminStatus} * @see {@link AdminResult} */ forCompletion(res: AdminResult, opt?: CompletionOpt): Promise<AdminResult>; /** * 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 * {@link TableResult} of the DDL operation is not available. To wait for * completion of the table DDL operation that you issued, use * {@link NoSQLClient#forCompletion}. This API waits until * the table has transitioned from an intermediate state like * {@link TableState.CREATING} or {@link TableState.UPDATING} to a * stable state like {@link TableState.ACTIVE}, at which point it * can be used. * * The result of this operation, if successful, is a {@link TableResult} * that shows the table state from the last poll. The * state of {@link 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. * @async * @param {string} tableName Table name * @param {TableState} tableState Desired table state * @param {CompletionOpt} [opt] Options object, see {@link CompletionOpt} * @returns {Promise} Promise of {@link TableResult} representing * result of the last poll * @see {@link NoSQLClient#getTable} * @see {@link NoSQLClient#tableDDL} * @see {@link NoSQLClient#forCompletion} */ forTableState(tableName: string, tableState: TableState, opt?: CompletionOpt): Promise<TableResult>; /** * 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 {@link ServiceType.KVSTORE}), in which * case it will result in error. * * Retrieves dynamic information associated with a table, as returned in * {@link 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 {@link 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 * {@link NoSQLClient#getTableUsage} using * {@link TableUsageOpt#startIndex} and {@link TableUsageOpt#limit} * parameters as shown in the example. However, the * recommended way is to call {@link NoSQLClient#tableUsageIterable} and * iterate over its result. * @example * 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. * * * ```ts * 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); * ``` * @async * @param {string} tableName Table name * @param {TableUsageOpt} [opt] Options object, see {@link TableUsageOpt}. * @returns {Promise} Promise of {@link TableUsageResult} * @see {@link TableUsageResult} * @see {@link #tableUsageIterable} */ getTableUsage(tableName: string, opt?: TableUsageOpt): Promise<TableUsageResult>; /** * 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 {@link ServiceType.KVSTORE}), in which * case it will result in error. * * Retrieves dynamic information associated with a table, as returned in * {@link 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 * {@link TableUsageResult}. Using this API is equivalent to paging table * usage records as shown in the example of * {@link NoSQLClient#getTableUsage}. * * Note that you must specify a time range (at least one of * {@link TableUsageOpt#startTime} and {@link TableUsageOpt#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 {@link TableUsageOpt#limit}. If * not specified, a default system limit will be used. * @example * Paging table usage records. * ```ts * 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); * } * } * ``` * @param {string} tableName Table name * @param {TableUsageOpt} [opt] Options object, see {@link TableUsageOpt} * @returns {AsyncIterable} Async iterable of {@link TableUsageResult} * @see {@link #getTableUsage} * @since 5.4 */ tableUsageIterable(tableName: string, opt?: TableUsageOpt): AsyncIterable<TableUsageResult>; /** * Retrieves information about indexes of the table as array of * {@link IndexInfo} objects. * @async * @param {string} tableName Table name * @param {GetIndexesOpt} [opt] Options object, see {@link GetIndexesOpt} * @returns {Promise} Promise of {@link IndexInfo}[] * @see {@link IndexInfo} */ getIndexes(tableName: string, opt?: GetIndexesOpt): Promise<IndexInfo[]>; /** * Retrieves information about specific index of the table as * {@link IndexInfo} object. * @async * @param {string} tableName Table name * @param {string} indexName Index name * @param {GetIndexOpt} [opt] Options object, see {@link GetIndexOpt} * @returns {Promise} Promise of {@link IndexInfo} * @see {@link NoSQLClient#getIndexes} */ getIndex(tableName: string, indexName: string, opt?: GetIndexOpt): Promise<IndexInfo>; /** * Lists tables, returning table names. If further information about a * specific table is desired the {@link 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 {@link ListTablesResult}. Names * are returned in alphabetical order to facilitate paging. * @async * @param {ListTablesOpt} [opt] Options object, see {@link ListTablesOpt} * @returns {Promise} Promise of {@link ListTablesResult} * @see {@link ListTablesResult} */ listTables(opt?: ListTablesOpt): Promise<ListTablesResult>; /** * Gets the row associated with a primary key. On success the value of the * row is available as property of {@link GetResult}. If there are no * matching rows, the operation is still successful the row property will * be set to null. * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName Table name * @param {RowKey<TRow>} key Primary key of the row, type determined by * {@link RowKey} * @param {GetOpt} [opt] Options object, see {@link GetOpt} * @returns {Promise} Promise of {@link GetResult} * @see {@link AnyKey} * @see {@link GetResult} */ get<TRow extends AnyRow>(tableName: string, key: RowKey<TRow>, opt?: GetOpt): Promise<GetResult<TRow>>; /** * 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 {@link RowVersion} of the existing value: * <ul> * <li>Use {@link PutOpt#ifAbsent} to do a put only if there is no * existing row that matches the primary key.</li> * <li>Use {@link PutOpt#ifPresent} to do a put only if there is an * existing row that matches the primary key.</li> * <li>Use {@link PutOpt#matchVersion} to do a put only if there is an * existing row that matches the primary key and its * {@link RowVersion} matches that provided by * {@link PutOpt#matchVersion}. * </li> * </ul> * Note that only one of {@link PutOpt#ifAbsent}, {@link PutOpt#ifPresent} * or {@link PutOpt#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 its {@link 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 * {@link PutOpt#returnExisting} is true and one of the following occurs: * <ul> * <li>{@link PutOpt#ifAbsent} is true and the operation fails because * the row already exists.</li> * <li>{@link PutOpt#matchVersion} is used and the operation fails because * the row exists and its {@link RowVersion} does not match.</li> * </ul> * The information about the result of the put operation is returned as * {@link PutResult}. Note that the failure cases discussed above that * resulted from inability to satisfy {@link PutOpt#ifAbsent}, * {@link PutOpt#ifPresent} or {@link PutOpt#matchVersion} options are * still considered successful as API calls, i.e. they result in * {@link PutResult} and not {@link NoSQLError}. See * {@link PutResult#success}. However if put fails for other reasons, * this API call will result in error instead. * * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName Table name * @param {TRow} row Table row * @param {PutOpt} [opt] Options object, see {@link PutOpt} * @returns {Promise} Promise of {@link PutResult} * @see {@link AnyRow} * @see {@link RowVersion} * @see {@link TimeToLive} * @see {@link PutResult} */ put<TRow extends AnyRow>(tableName: string, row: TRow, opt?: PutOpt): Promise<PutResult<TRow>>; /** * Performs a put if there is no existing row that matches the primary * key. This API is a shorthand for {@link NoSQLClient#put} with * {@link PutOpt#ifAbsent} set to true. * @async * @typeParam TRow Type of table row instance, same as in * {@link NoSQLClient#put}. * @param {string} tableName Table name * @param {TRow} row Row, same as in {@link NoSQLClient#put} * @param {PutIfOpt} [opt] Options object, see {@link PutIfOpt} * @returns {Promise} Promise of {@link PutResult} * @see {@link NoSQLClient#put} */ putIfAbsent<TRow extends AnyRow>(tableName: string, row: TRow, opt?: PutIfOpt): Promise<PutResult<TRow>>; /** * Performs a put if there is existing row that matches the primary * key. This API is a shorthand for {@link NoSQLClient#put} with * {@link PutOpt#ifPresent} set to true. * @async * @typeParam TRow Type of table row instance, same as in * {@link NoSQLClient#put}. * @param {string} tableName Table name * @param {TRow} row Row, same as in {@link NoSQLClient#put} * @param {PutIfOpt} [opt] Options object, see {@link PutIfOpt} * @returns {Promise} Promise of {@link PutResult} * @see {@link NoSQLClient#put} */ putIfPresent<TRow extends AnyRow>(tableName: string, row: TRow, opt?: PutIfOpt): Promise<PutResult<TRow>>; /** * Performs a put if there is an existing row that matches the primary key * and its {@link RowVersion} matches the value provided. This API is a * shorthand for {@link NoSQLClient#put} with {@link PutOpt#matchVersion} * specified. * @async * @typeParam TRow Type of table row instance, same as in * {@link NoSQLClient#put}. * @param {string} tableName Table name * @param {TRow} row Row, same as in {@link NoSQLClient#put} * @param {RowVersion} matchVersion {@link RowVersion} to match * @param {PutIfOpt} [opt] Options object, see {@link PutIfOpt} * @returns {Promise} Promise of {@link PutResult} * @see {@link NoSQLClient#put} */ putIfVersion<TRow extends AnyRow>(tableName: string, row: TRow, matchVersion: RowVersion, opt?: PutIfOpt): Promise<PutResult<TRow>>; /** * 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 {@link RowVersion} of an existing row matches that supplied * {@link DeleteOpt#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 {@link DeleteResult} if a delete operation fails because of * a version mismatch. The existing row information will only be returned * if {@link DeleteOpt#returnExisting} is true and * {@link DeleteOpt#matchVersion} is set and the operation fails because * the row exists and its version does not match. Use of * {@link DeleteOpt#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 * {@link DeleteResult}. Note that the failures to delete if the row * doesn't exist or if {@link DeleteOpt#matchVersion} is set and the * version did not match are still considered successful as API calls, * i.e. they result in {@link DeleteResult} and not {@link NoSQLError}, * see {@link DeleteResult#success}. However if delete fails for other * reasons, this API call will result in error instead. * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName Table name * @param {RowKey<TRow>} key Primary key of the row, type determined by * {@link RowKey} * @param {DeleteOpt} [opt] Options object, see {@link DeleteOpt} * @returns {Promise} Promise of {@link DeleteResult} * @see {@link AnyKey} * @see {@link RowVersion} * @see {@link DeleteResult} */ delete<TRow extends AnyRow>(tableName: string, key: RowKey<TRow>, opt?: DeleteOpt): Promise<DeleteResult<TRow>>; /** * Performs a delete if there is an existing row that matches the primary * key and its {@link RowVersion} matches the value provided. This API is * a shorthand for {@link NoSQLClient#delete} with * {@link DeleteOpt#matchVersion} specified. * @async * @typeParam TRow Type of table row instance, same as in * {@link NoSQLClient#delete}. * @param {string} tableName Table name * @param {RowKey<TRow>} key Primary key, same as in * {@link NoSQLClient#delete} * @param {RowVersion} matchVersion {@link RowVersion} to match * @param {DeleteIfOpt} [opt] Options object, see {@link DeleteIfOpt} * @returns {Promise} Promise of {@link DeleteResult} * @see {@link NoSQLClient#delete} */ deleteIfVersion<TRow extends AnyRow>(tableName: string, key: RowKey<TRow>, matchVersion: RowVersion, opt?: DeleteIfOpt): Promise<DeleteResult<TRow>>; /** * 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 {@link MultiDeleteOpt#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 * {@link 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 * {@link MultiDeleteResult} that can be used to continue the operation. * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName Table name * @param {Key} key Partial primary key * @param {MultiDeleteOpt} [opt] Options object, {@link MultiDeleteOpt} * @returns {Promise} Promise of {@link MultiDeleteResult} * @see {@link AnyKey} * @see {@link FieldRange} * @see {@link MultiDeleteResult} */ deleteRange<TRow extends AnyRow>(tableName: string, key: RowKey<TRow>, opt?: MultiDeleteOpt): Promise<MultiDeleteResult>; /** * 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: * <ul> * <li>The max number of individual operations (put, delete) in a single * call to this API is 50.</li> * <li>The total request size is limited to 25MB.</li> * </ul> * The result of this operation is returned as * {@link 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 * {@link WriteOperation#abortOnFail} set to true, or if * {@link WriteMultipleOpt#abortOnFail} is true, then the index and * execution result of the failed sub operation will be stored in * {@link WriteMultipleResult} (thus the API call in this case is still * successful and no error results). * * Note that in addition to {@link WriteMultipleOpt} passed to this API, * each sub operation can pass its own put or delete options in * {@link WriteOperation} Each option explicitly set in * {@link WriteOperation} will take precedence over its value in * {@link WriteMultipleOpt}, otherwise {@link 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 * {@link WriteOperation#tableName}. * @overload * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName 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 * {@link WriteOperation#tableName} for any operation will result in error * @param {WriteOperation[]} operations Array of * {@link WriteOperation} objects each representing single put or delete * operation, see {@link WriteOperation} * @param {WriteMultipleOpt} [opt] Options object, see * {@link WriteMultipleOpt} * @returns {Promise} Promise of {@link WriteMultipleResult} */ writeMany<TRow extends AnyRow>(tableName: string, operations: WriteOperation<TRow>[], opt?: WriteMultipleOpt): Promise<WriteMultipleResult<TRow>>; /** * @overload * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {WriteOperation[]} operations Array of * {@link WriteOperation} objects each representing single put or delete * operation, see {@link WriteOperation} * @param {WriteMultipleOpt} [opt] Options object, see * {@link WriteMultipleOpt} * @returns {Promise} Promise of {@link WriteMultipleResult} * @see {@link WriteOperation} * @see {@link WriteMultipleResult} */ writeMany<TRow extends AnyRow>(operations: WriteOperation<TRow>[], opt?: WriteMultipleOpt): Promise<WriteMultipleResult<TRow>>; /** * @overload * @async * @param {WriteOperation} operations Array of {@link WriteOperation} * objects each representing single put or delete operation, see * {@link WriteOperation} * @param {WriteMultipleOpt} [opt] Options object, see * {@link WriteMultipleOpt} * @returns {Promise} Promise of {@link WriteMultipleResult} * @see {@link WriteOperation} * @see {@link WriteMultipleResult} */ writeMany(operations: WriteOperation[], opt?: WriteMultipleOpt): Promise<WriteMultipleResult>; /** * 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 {@link NoSQLClient#writeMany} with the * following simplifications: * <ul> * <li>The sequence contains only put operations.</li> * <li>All operations are for a single table.</li> * <li>Options are specified only in {@link PutManyOpt} for this API * and are same for all put sub operations (no per-sub-operation options). * </li> * </ul> * This API may be more convenient to use than * {@link NoSQLClient#writeMany} when applicable. * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName * @param {TRow[]} rows Array of rows to put * @param {PutManyOpt} [opt] Options object, see {@link PutManyOpt} * @returns {Promise} Promise of {@link WriteMultipleResult} * @see {@link writeMany} */ putMany<TRow extends AnyRow>(tableName: string, rows: TRow[], opt?: PutManyOpt): Promise<WriteMultipleResult<TRow>>; /** * 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 {@link NoSQLClient#writeMany} with the * following simplifications: * <ul> * <li>The sequence contains only delete operations.</li> * <li>All operations are for a single table.</li> * <li>Options are specified only in {@link DeleteManyOpt} for this API * and are same for all delete sub-operations (no per-sub-operation * options).</li> * </ul> * This API may be more more convenient to use than * {@link NoSQLClient#writeMany} when applicable. * @async * @typeParam TRow Type of table row instance. Must include primary key * fields. Defaults to {@link AnyRow}. * @param {string} tableName * @param {TKey[]} keys Array of primary keys to delete * @param {DeleteManyOpt} [opt] Options object, see {@link