oracle-nosqldb/lib/nosql_client.js

Node.js driver for Oracle NoSQL Database

/*-
 * 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/
 */

'use strict';

const ops = require('./ops');
const NoSQLClientImpl = require('./nosql_client_impl');

/**
 * Defines NoSQLClient, which is the point of access to the
 * Oracle NoSQL Database Cloud service.
 */

/**
 * @classdesc 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.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * 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>
 * <p>
 * Each method of NoSQLClient also takes an optional <em>opt</em>
 * 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 <em>opt</em> parameter and is also not present in
 * {@link Config}, the driver will use default values.
 * <p>
 * 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.
 * <p>
 * <em>For cloud service only:</em> for each method you may provide
 * <em>opt.compartment</em> 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. <em>compartmentA.compartmentB.compartmentC</em>
 * <p>
 * Alternatively, instead of setting <em>opt.compartment</em>
 * you may prefix the table name with its compartment name (for top-level
 * compartments) or compartment path (for nested compartments), e.g.
 * <em>compartmentA.compartmentB.compartmentC:myTable</em>.
 * 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.
 *
 * @fires NoSQLClient#error
 * @fires NoSQLClient#retryable
 * @fires NoSQLClient#consumedCapacity
 * @fires NoSQLClient#tableState
 *
 * @tutorial connect-cloud
 * @tutorial connect-on-prem
 * @tutorial tables
 *
 * @example // Using NoSQLClient with async-await
 *
 * const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
 *
 * async function test() {
 *      let client;
 *      try {
 *          client = new NoSQLClient('config.json');
 *          let res = await client.tableDDL(
 *              'CREATE TABLE foo(id INTEGER, name STRING, PRIMARY KEY(id))',
 *              {
 *                  tableLimits: {
 *                      readUnits: 100,
 *                      writeUnits: 100,
 *                      storageGB: 50
 *                  }
 *              }
 *          );
 *          console.log('Table: %s, state: %s', res.tableName,
 *              res.tableState);
 *          await client.forCompletion(res);
 *          res = await client.put('foo', { id: 1, name: 'test' });
 *          res = await client.get('foo', { id: 1 });
 *          console.log(res.row);
 *          //..........
 *      } catch(err) {
 *          //handle errors
 *      } finally {
 *          if (client) {
 *              client.close();
 *          }
 *      }
 * }
 */
class NoSQLClient extends NoSQLClientImpl {

    /**
     * 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
     * <em>module.exports</em> should be set to the {@link Config} object).
     * Note that you may pass <em>null</em> 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) {
        super(config);
    }

    /**
     * Returns the version of the driver.
     * @returns {string} The version of the driver
     */
    static get version() {
        return require('./constants').PACKAGE_VERSION;
    }

    /**
     * Returns the service type of used by this {@link NoSQLClient} instance.
     * @returns {ServiceType} Service type
     */
    get serviceType() {
        return this._config.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 <em>await</em> for
     * it if you need to perform an action upon its completion.
     * @see {@link ServiceType}
     */
    close() {
        return super.close();
    }

    /**
     * Obtains and caches authorization information in advance of performing
     * database operations.
     * <p>
     * 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.
     * <p> 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.
     * <p>
     * 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.
     * <p>
     * Calling this method is equivalient to calling
     * {@link AuthorizationProvider}#getAuthorization 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.
     * <p>
     * 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 {@link NoSQLClient#precacheAuth} on new {@link NoSQLClient}
     * // instance.
     * 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() {
        return super._precacheAuth();
    }

    /**
     * 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * Alternatively, if <em>opt.complete</em> is set to true, this API will
     * complete (i.e. the returned <em>Promise</em> 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, <em>opt.timeout</em>
     * 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
     * <em>opt.delay</em> to specify polling delay (see
     * {@link NoSQLClient#forCompletion}).
     * @async
     * @param {string} stmt SQL statement
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#ddlTimeout (if
     * <em>opt.complete</em> is true, 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)
     * @param {TableLimits} [opt.tableLimits] Specifies new table limits for
     * a table. See {@link TableLimits}.  Note that this property is required
     * when creating a table
     * @param {TableETag} [opt.matchETag] Cloud Service only. Entity tag that
     * must be matched for the operation to proceed. See {@link TableETag}
     * @param {DefinedTags} [opt.definedTags] Cloud Service only. Defined tags
     * to use for the operation.  See {@link DefinedTags}
     * @param {FreeFormTags} [opt.freeFormTags] Cloud Service only. Free-form
     * tags to use for the operation.  See {@link FreeFormTags}
     * @param {boolean} [opt.complete] If set to true, the returned
     * <em>Promise</em> will only resolve when the operation is completed and
     * the table state becomes {@link TableState.ACTIVE} or
     * {@link TableState.DROPPED} (if the operation was "DROP TABLE")
     * @param {number} [opt.delay] If <em>opt.complete</em> is true, specifies
     * delay between successive polls while waiting for operation completion.
     * Defaults to {@link Config}#tablePollDelay.  Has no effect if
     * <em>opt.complete</em> is not enabled
     * @returns {Promise} Promise of {@link TableResult}
     * @see {@link TableResult}
     * @see {@link NoSQLClient#forCompletion}
     */
    tableDDL(stmt, opt) {
        const req = {
            api: this.tableDDL,
            stmt,
            opt
        };
        return opt != null && opt.complete ?
            this._withCompletion(ops.TableDDLOp, req) :
            this._execute(ops.TableDDLOp, req);
    }

    /**
     * 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.
     * <p>
     * Sets new limits of throughput and storage for existing table.
     * <p>
     * Same considerations as described in {@link NoSQLClient#tableDDL} about
     * long-running operations, using {@link NoSQLClient#forCompletion} and
     * options <em>opt.complete</em> and <em>opt.delay</em> apply to this API.
     * See {@link NoSQLClient#tableDDL}.
     * @async
     * @param {string} tableName Table name
     * @param {TableLimits} tableLimits New table limits for the table
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#ddlTimeout (if
     * <em>opt.complete</em> is true, 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)
     * @param {TableETag} [opt.matchETag] Cloud Service only. Entity tag that
     * must be matched for the operation to proceed. See {@link TableETag}
     * @param {boolean} [opt.complete] If set to true, the returned
     * <em>Promise</em> will only resolve when the operation is completed and
     * the table state becomes {@link TableState.ACTIVE}
     * @param {number} [opt.delay] If <em>opt.complete</em> is true, specifies
     * delay between successive polls while waiting for operation completion.
     * Defaults to {@link Config}#tablePollDelay.  Has no effect if
     * <em>opt.complete</em> is not enabled
     * @returns {Promise} Promise of {@link TableResult}
     * @see {@link TableResult}
     * @see {@link NoSQLClient#tableDDL}
     */
    setTableLimits(tableName, tableLimits, opt) {
        opt = this._assignOpt(opt, { tableLimits });
        const req = {
            api: this.setTableLimits,
            tableName,
            opt
        };
        return opt.complete ?
            this._withCompletion(ops.TableLimitsOp, req) :
            this._execute(ops.TableLimitsOp, req);
    }

    /**
     * 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.
     * <p>
     * Sets defined and free-form tags on existing table.
     * <p> See {@link DefinedTags} and {@link FreeFormTags} for more
     * information on tagging.
     * <p>
     * Same considerations as described in {@link NoSQLClient#tableDDL} about
     * long-running operations, using {@link NoSQLClient#forCompletion} and
     * options <em>opt.complete</em> and <em>opt.delay</em> 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 <em>null</em>
     * 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
     * <em>null</em> (or omit if not using <em>opt</em> parameter) if you with
     * to set only defined tags.
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#ddlTimeout (if
     * <em>opt.complete</em> is true, 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)
     * @param {TableETag} [opt.matchETag] Cloud Service only. Entity tag that
     * must be matched for the operation to proceed. See {@link TableETag}
     * @param {boolean} [opt.complete] If set to true, the returned
     * <em>Promise</em> will only resolve when the operation is completed and
     * the table state becomes {@link TableState.ACTIVE}
     * @param {number} [opt.delay] If <em>opt.complete</em> is true, specifies
     * delay between successive polls while waiting for operation completion.
     * Defaults to {@link Config}#tablePollDelay.  Has no effect if
     * <em>opt.complete</em> is not enabled
     * @returns {Promise} Promise of {@link TableResult}
     * @see {@link DefinedTags}
     * @see {@link FreeFormTags}
     * @see {@link TableResult}
     * @see {@link NoSQLClient#tableDDL}
     */
    setTableTags(tableName, definedTags, freeFormTags, opt) {
        opt = this._assignOpt(opt, { definedTags, freeFormTags });
        const req = {
            api: this.setTableTags,
            tableName,
            opt
        };
        return opt.complete ?
            this._withCompletion(ops.TableLimitsOp, req) :
            this._execute(ops.TableLimitsOp, req);
    }

    /**
     * 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 {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @returns {Promise} Promise of {@link TableResult}
     * @see {@link NoSQLClient#tableDDL}
     */
    getTable(table, opt) {
        return this._execute(ops.GetTableOp, {
            api: this.getTable,
            table,
            opt
        });
    }

    /**
     * Waits asynchronously for the table to reach a desired state.  This is
     * achieved by polling the table at specified intervals.
     * <p>
     * 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.
     * <p>
     * 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 {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds, i.e. how long to keep polling for desired table state.
     * Defaults to {@link Config}#tablePollTimeout
     * @param {number} [opt.delay] Delay in milliseconds between
     * successive polls, determines how often the polls are performed.
     * Defaults to {@link Config}#tablePollDelay
     * @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, tableState, opt) {
        return this._forTableState(tableName, tableState, opt);
    }

    /**
     * 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.
     * <p>
     * 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}.
     * <p>
     * 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.
     * <p>
     * Because the number of table usage records can be very large, you may
     * page the results over multiple calls to
     * {@link NoSQLClient#getTableUsage} using <em>opt.startIndex</em> and
     * <em>opt.limit</em> parameters as shown in the example.  However, the
     * recommended way is to call {@link NoSQLClient#tableUsageIterable} and
     * iterate over its result.
     * @example <caption>Paging over table usage records</caption>
     * // 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);
     * @async
     * @param {string} tableName Table name
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {Date|string|number} [opt.startTime]  Start time for the time
     * period.  Can be JavaScript Date, string representing date and time or
     * number of milliseconds since epoch (January 1, 1970, 00:00:00 UTC).
     * For string representation see <em>Date.parse()</em>.  If time
     * range is not specified, the most recent complete usage record is
     * returned
     * @param {Date|string|number}  [opt.endTime]  End time for the time
     * period, represented same as opt.startTime
     * @param {number} [opt.limit]  Limit to the number of usage records
     * desired. If not specified or value is 0, there is no limit, but not all
     * usage records may be returned due to size limitations
     * @param {number} [opt.startIndex=0] Index at which to start returning
     * table usage records.  To page table usage records, set this value to
     * {@link TableUsageResult}#nextIndex returned from previous call to
     * {@link NoSQLClient#getTableUsage}. These operations are best done in a
     * loop. See the example
     * @returns {Promise} Promise of {@link TableUsageResult}
     * @see {@link TableUsageResult}
     * @see {@link #tableUsageIterable}
     */
    getTableUsage(tableName, opt) {
        return this._execute(ops.TableUsageOp, {
            api: this.getTableUsage,
            tableName,
            opt
        });
    }

    /**
     * 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.
     * <p>
     * Retrieves dynamic information associated with a table, as returned in
     * {@link TableUsageResult}.
     * <p>
     * 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 <em>for-await-of</em> 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}.
     * <p>
     * Note that you must specify a time range (at least one of
     * <em>opt.startTime</em> and <em>opt.endTime</em> for which to return
     * table usage records, otherwise only one (the most recent) table usage
     * record will be returned.
     * <p>
     * You may optionally specify a limit on the number of table usage records
     * returned in each partial result using <em>opt.limit</em>. If not
     * specified, a default system limit will be used.
     * @example <caption>Paging table usage records</caption>
     * 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 {object} opt Options object. See <em>opt</em> parameter of
     * {@link NoSQLClient#getTableUsage}.  The same options are available,
     * except <em>opt.startIndex</em>
     * @returns {Promise} Promise of {@link TableUsageResult}
     * @see {@link #getTableUsage}
     * @since 5.4
     */
    tableUsageIterable(tableName, opt) {
        return this._tableUsageIterable(tableName, opt);
    }

    /**
     * Retrieves information about indexes of the table as array of
     * {@link IndexInfo} objects.
     * @async
     * @param {string} tableName Table name
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {string} [opt.indexName]  Return information only about specific
     * index, same as {@link NoSQLClient#getIndex}.  If not specified,
     * information on all indexes is returned
     * @returns {Promise} Promise of {@link IndexInfo}[]
     * @see {@link IndexInfo}
     */
    getIndexes(tableName, opt) {
        return this._execute(ops.GetIndexesOp, {
            api: this.getIndexes,
            tableName,
            opt
        });
    }

    /**
     * Retrieves information about specific index of the table as
     * {@link IndexInfo} object.
     * @async
     * @param {string} tableName Table name
     * @param {string} indexName Index name
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @returns {Promise} Promise of {@link IndexInfo}
     * @see {@link NoSQLClient#getIndexes}
     */
    getIndex(tableName, indexName, opt) {
        return this._getIndex(tableName, indexName, opt);
    }

    /**
     * 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 {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information. Only tables belonging to the given compartment (but not
     * its child compartments) will be listed
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {number} [opt.startIndex]  The index to use to start returning
     * table names. This is related to the {@link ListTablesResult}#lastIndex
     * from a previous request and can be used to page table names. If not
     * set, the list starts at index 0
     * @param {number} [opt.limit] The maximum number of table names to return
     * in the operation. If not set or set to 0, there is no limit
     * @param {string} [opt.namespace] On-premise only.  If set, list tables
     * from given namespace only, otherwise list all tables for the user.
     * @returns {Promise} Promise of {@link ListTablesResult}
     * @see {@link ListTablesResult}
     */
    listTables(opt) {
        return this._execute(ops.ListTablesOp, {
            api: this.listTables,
            opt
        });
    }

    /**
     * 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
     * @param {string} tableName Table name
     * @param {Key} key Primary {@link Key} of the row
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {Consistency} [opt.consistency] {@link Consistency} used for
     * the operation.  Defaults to {@link Config}#Consistency
     * @returns {Promise} Promise of {@link GetResult}
     * @see {@link Key}
     * @see {@link GetResult}
     */
    get(tableName, key, opt) {
        return this._execute(ops.GetOp, {
            api: this.get,
            tableName,
            key,
            opt
        });
    }

    /**
     * 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.
     * <p>
     * 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.
     * <p>
     * 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 Version} of the existing value:
     * <ul>
     * <li>Use <em>opt.isAbsent</em> to do a put only if there is no existing
     * row that matches the primary key.</li>
     * <li>Use <em>opt.ifPresent</em> to do a put only if there is an
     * existing row that matches the primary key.</li>
     * <li>Use <em>opt.matchVersion</em> to do a put only if there is an
     * existing row that matches the primary key <em>and</em> its
     * {@link Version} matches that provided by <em>opt.matchVersion</em>.
     * </li>
     * </ul>
     * Note that only one of <em>opt.isAbsent</em>, <em>opt.ifPresent</em> or
     * <em>opt.matchVersion</em> options may be specified for given put
     * operation.
     * <p>
     * It is also possible, on failure, to return information about the
     * existing row. The row, including its {@link 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 <em>opt.returnExisting</em> is
     * true and one of the following occurs:
     * <ul>
     * <li><em>opt.isAbsent</em> is true and the operation fails because
     * the row already exists.</li>
     * <li><em>opt.matchVersion</em> is used and the operation fails because
     * the row exists and its {@link Version} 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 <em>opt.isAbsent</em>,
     * <em>opt.ifPresent</em> or <em>opt.matchVersion</em> 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
     * @param {string} tableName Table name
     * @param {Row} row Table {@link Row}
     * @param {object} [opt] Options object:
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {boolean} [opt.ifAbsent] If set to true, do put
     * only if there is no existing row that matches the primary key
     * @param {boolean} [opt.ifPresent] If set to true, do put only if
     * there is existing row that matches the primary key
     * @param {Version} [opt.matchVersion] If set, do a put only if there is
     * an existing row that matches the primary key and its {@link Version}
     * matches the value provided
     * @param {boolean} [opt.returnExisting] If set to true, existing
     * row and its version will be returned as part of {@link PutResult}
     * if put operation fails as per discussion above
     * @param {Durability} [opt.durability] On-premises only. Set the desired
     * durability for master/replica sync/acks.  Defaults to
     * {@link Config}#durability or if not set, the default server-side
     * durability settings are used. See {@link Durability}
     * @param {TimeToLive|number} [opt.ttl] Sets {@link TimeToLive} value,
     * causing the time to live on the row to be set to the specified value
     * on put. This value overrides any default time to live setting on
     * the table
     * @param {boolean} [opt.updateTTLToDefault] If set to true, and
     * there is an existing row, causes the operation to update the time to
     * live (TTL) value of the row based on the table's default TTL if set.
     * If the table has no default TTL this state has no effect.  By default
     * updating an existing row has no effect on its TTL.  This option cannot
     * be specified if <em>opt.ttl</em> is specified
     * @param {boolean} [opt.exactMatch] If true the value must be an exact
     * match for the table schema or the operation will fail. An exact match
     * means that there are no required fields missing and that there are no
     * extra, unknown fields. The default behavior is to not require an exact
     * match
     * @param {number} [opt.identityCacheSize] Sets the number of generated
     * identity values that are requested from the server during a put. This
     * takes precedence over the DDL identity CACHE option set during creation
     * of the identity column.  Must be positive integer.  If not set, the DDL
     * identity CACHE value is used
     * @returns {Promise} Promise of {@link PutResult}
     * @see {@link Row}
     * @see {@link Version}
     * @see {@link TimeToLive}
     * @see {@link PutResult}
     */
    put(tableName, row, opt) {
        return this._execute(ops.PutOp, {
            api: this.put,
            tableName,
            row,
            opt
        });
    }

    /**
     * Performs a put if there is no existing row that matches the primary
     * key.  This API is a shorthand for {@link NoSQLClient#put} with
     * <em>opt.ifAbsent</em> set to true.
     * @async
     * @param {string} tableName Table name
     * @param {Row} row Row, same as in {@link NoSQLClient#put}
     * @param {object} opt Options object, see below
     * @param {string} [opt.compartment] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.timeout] Same as in {@link NoSQLClient#put}
     * @param {Durability} [opt.durability] Same as in {@link NoSQLClient#put}
     * @param {boolean} [opt.returnExisting] Same as in
     * {@link NoSQLClient#put}
     * @param {TimeToLive|number} [opt.ttl] Same as in {@link NoSQLClient#put}
     * @param {boolean} [opt.exactMatch] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.identityCacheSize] Same as in
     * {@link NoSQLClient#put}
     * @returns {Promise} Promise of {@link PutResult}
     * @see {@link NoSQLClient#put}
     */
    putIfAbsent(tableName, row, opt) {
        return this._execute(ops.PutOp, {
            api: this.putIfAbsent,
            tableName,
            row,
            opt: this._assignOpt(opt, { ifAbsent: true })
        });
    }

    /**
     * Performs a put if there is existing row that matches the primary
     * key.  This API is a shorthand for {@link NoSQLClient#put} with
     * <em>opt.ifPresent</em> set to true.
     * @async
     * @param {string} tableName Table name
     * @param {Row} row Row, same as in {@link NoSQLClient#put}
     * @param {object} opt Options object, see below
     * @param {string} [opt.compartment] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.timeout] Same as in {@link NoSQLClient#put}
     * @param {Durability} [opt.durability] Same as in {@link NoSQLClient#put}
     * @param {TimeToLive|number} [opt.ttl] Same as in {@link NoSQLClient#put}
     * @param {boolean} [opt.updateTTLToDefault] Same as in
     * {@link NoSQLClient#put}
     * @param {boolean} [opt.exactMatch] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.identityCacheSize] Same as in
     * {@link NoSQLClient#put}
     * @returns {Promise} Promise of {@link PutResult}
     * @see {@link NoSQLClient#put}
     */
    putIfPresent(tableName, row, opt) {
        return this._execute(ops.PutOp, {
            api: this.putIfPresent,
            tableName,
            row,
            opt: this._assignOpt(opt, { ifPresent: true })
        });
    }

    /**
     * Performs a put if there is an existing row that matches the primary key
     * and its {@link Version} matches the value provided.  This API is a
     * shorthand for {@link NoSQLClient#put} with <em>opt.matchVersion</em>
     * specified.
     * @async
     * @param {string} tableName Table name
     * @param {Row} row Row, same as in {@link NoSQLClient#put}
     * @param {Version} matchVersion {@link Version} to match
     * @param {object} opt Options object, see below
     * @param {string} [opt.compartment] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.timeout] Same as in {@link NoSQLClient#put}
     * @param {Durability} [opt.durability] Same as in {@link NoSQLClient#put}
     * @param {boolean} [opt.returnExisting] Same as in
     * {@link NoSQLClient#put}
     * @param {TimeToLive|number} [opt.ttl] Same as in {@link NoSQLClient#put}
     * @param {boolean} [opt.updateTTLToDefault] Same as in
     * {@link NoSQLClient#put}
     * @param {boolean} [opt.exactMatch] Same as in {@link NoSQLClient#put}
     * @param {number} [opt.identityCacheSize] Same as in
     * {@link NoSQLClient#put}
     * @returns {Promise} Promise of {@link PutResult}
     * @see {@link NoSQLClient#put}
     */
    putIfVersion(tableName, row, matchVersion, opt) {
        return this._execute(ops.PutOp, {
            api: this.putIfVersion,
            tableName,
            row,
            opt: this._assignOpt(opt, { matchVersion })
        });
    }

    /**
     * Deletes a row from a table. The row is identified using a primary key
     * value.
     * <p>
     * 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 Version} of an existing row matches that supplied
     * <em>opt.matchVersion</em>
     * <p>
     * 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 <em>opt.returnExisting</em> is true and <em>opt.matchVersion</em> is
     * set and the operation fails because the row exists and its version does
     * not match.  Use of <em>opt.returnExisting</em> may result in additional
     * consumed read capacity. If the operation is successful there will be no
     * information returned about the previous row.
     * <p>
     * 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 <em>opt.matchVersion</em> 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
     * @param {string} tableName Table name
     * @param {Key} key Primary {@link Key} of the row
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Cloud service only. Compartment id
     * or name to use for this operation. Defaults to
     * {@link Config}#compartment. See {@link Config}#compartment for more
     * information
     * @param {number} [opt.timeout] Timeout for the operation in
     * milliseconds.  Defaults to {@link Config}#timeout
     * @param {boolean} [opt.returnExisting] If set to true, existing
     * row and its version will be returned as part of {@link DeleteResult}
     * if delete operation fails because of version mismatch as discussed
     * above
     * @param {Durability} [opt.durability] On-premises only. Set the desired
     * durability for master/replica sync/acks.  Defaults to
     * {@link Config}#durability or if not set, the default server-side
     * durability settings are used. See {@link Durability}
     * @param {Version} [opt.matchVersion] If set, delete only if
     * there is an existing row that matches the primary key and its
     * {@link Version} matches the value provided
     * @returns {Promise} Promise of {@link DeleteResult}
     * @see {@link Key}
     * @see {@link Version}
     * @see {@link DeleteResult}
     */
    delete(tableName, key, opt) {
        return this._execute(ops.DeleteOp, {
            api: this.delete,
            tableName,
            key,
            opt
        });
    }

    /**
     * Performs a delete if there is an existing row that matches the primary
     * key and its {@link Version} matches the value provided.  This API is a
     * shorthand for {@link NoSQLClient#delete} with <em>opt.matchVersion</em>
     * specified.
     * @async
     * @param {string} tableName Table name
     * @param {Key} key Primary key, same as in {@link NoSQLClient#delete}
     * @param {Version} matchVersion {@link Version} to match
     * @param {object} [opt] Options object, see below
     * @param {string} [opt.compartment] Same as in
     * {@link NoSQLClient#delete}
     * @param {number} [opt.timeout] Same as in {@link NoSQLClient#delete}
     * @param {boolean} [opt.returnExisting] Same as in
     * {@link NoSQLClient#delete}
     * @param {Durability} [opt.durability] Same as in
     * {@link NoSQLClient#delete}
     * @returns {Promise} Promise of {@link DeleteResult}
     * @see {@link NoSQLClient#delete}
     */
    deleteIfVersion(tableName, key, matchVersion, opt) {
        return this._execute(ops.DeleteOp, {
            api: this.deleteIfVersion,
            tableName,
            key,
            opt: this._assignOpt(opt, { matchVersion })
        });
    }

    /**
     * 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 ra