Package oracle.kv.table

# Interface TableAPI

public interface TableAPI
TableAPI is a handle for the table interface to an Oracle NoSQL store. Tables are an independent layer implemented on top of the `key/value interface`. While the two interfaces are not incompatible, in general applications will use one or the other. To create a TableAPI instance use `getTableAPI()`.

The table interface is required to use secondary indexes and supported data types.

Tables are similar to tables in a relational database. They are named and contain a set of strongly typed records, called rows. Rows in an Oracle NoSQL Database table are analogous to rows in a relational system and each row has one or more named, typed data values. These fields can be compared to a relational database column. A single top-level row in a table is contained in a `Row` object. Row is used as return value for TableAPI get operations as well as a key plus value object for TableAPI put operations. All rows in a given table have the same fields. Tables have a well-defined primary key which comprises one or more of its fields, in order. Primary key fields must be simple (single-valued) data types.

The data types supported in tables are well-defined and include simple single-valued types such as Integer, String, Date, etc., in addition to several complex, multi-valued types -- Array, Map, and Record. Complex objects allow for creation of arbitrarily complex, nested rows.

All operations on this interface include parameters that supply optional arguments to control non-default behavior. The types of these parameter objects varies depending on whether the operation is a read, update, or a multi-read style operation returning more than one result or an iterator.

In order to control, and take advantage of sharding across partitions tables may be defined in a hierarchy. A top-level table is one without a parent and may be defined in a way such that its primary key spreads the table rows across partitions. The primary key for this sort of table has a complete shard key but an empty minor key. Tables with parents always have a primary key with a minor key. The primary key of a child table comprises the primary key of its immediate parent plus the fields defined in the child table as being part of its primary key. This means that the fields of a child table implicitly include the primary key fields of all of its ancestors.

Some of the methods in this interface include `MultiRowOptions` which can be used to cause operations to return not only rows from the target table but from its ancestors and descendant tables as well. This allows for efficient and transactional mechanisms to return related groups of rows. The MultiRowOptions object is also used to specify value ranges that apply to the operation. Iterators returned by methods of this interface can only be used safely by one thread at a time unless synchronized externally.

Since:
  3.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `SYSDEFAULT_NAMESPACE_NAME`
  Name of "sysdefault" namespace.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `delete(PrimaryKey key, ReturnRow prevRow, WriteOptions writeOptions)`
  Deletes a row from a table.
  `CompletableFuture<Boolean>`
  `deleteAsync(PrimaryKey key, ReturnRow prevRow, WriteOptions writeOptions)`
  Deletes a row from a table, returning a future to manage the asynchronous operation.
  `boolean`
  `deleteIfVersion(PrimaryKey key, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)`
  Deletes a row from a table but only if its version matches the one specified in matchVersion.
  `CompletableFuture<Boolean>`
  `deleteIfVersionAsync(PrimaryKey key, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)`
  Deletes a row from a table, but only if its version matches the one specified in `matchVersion`, returning a future to manage the asynchronous operation.
  `ExecutionFuture`
  `execute(String statement)`
  Deprecated.
  since 3.3 in favor of `KVStore.execute(String)`
  `List<TableOperationResult>`
  `execute(List<TableOperation> operations, WriteOptions writeOptions)`
  This method provides an efficient and transactional mechanism for executing a sequence of operations associated with tables that share the same shard key portion of their primary keys.
  `CompletableFuture<List<TableOperationResult>>`
  `executeAsync(List<TableOperation> operations, WriteOptions writeOptions)`
  This method provides an efficient and transactional mechanism for executing a sequence of operations associated with tables that share the same shard key portion of their primary keys, returning a future to manage the asynchronous operation.
  `StatementResult`
  `executeSync(String statement)`
  Deprecated.
  since 3.3 in favor of `KVStore.executeSync(java.lang.String)`
  `Row`
  `get(PrimaryKey key, ReadOptions readOptions)`
  Gets the `Row` associated with the primary key.
  `CompletableFuture<Row>`
  `getAsync(PrimaryKey key, ReadOptions readOptions)`
  Gets the `Row` associated with the primary key, returning a future to manage the asynchronous operation.
  `Table`
  `getTable(String fullNamespaceName)`
  Gets an instance of a table.
  `Table`
  `getTable(String namespace, String tableFullName)`
  Gets an instance of a table.
  `TableOperationFactory`
  `getTableOperationFactory()`
  Returns a `TableOperationFactory` to create operations passed to `execute(java.lang.String)`.
  `Map<String,Table>`
  `getTables()`
  Gets all known tables.
  `Map<String,Table>`
  `getTables(String namespace)`
  Gets all known tables in the specified namespace.
  `Set<String>`
  `listNamespaces()`
  Gets all known namespaces.
  `int`
  `multiDelete(PrimaryKey key, MultiRowOptions getOptions, WriteOptions writeOptions)`
  Deletes multiple rows from a table in an atomic operation.
  `CompletableFuture<Integer>`
  `multiDeleteAsync(PrimaryKey key, MultiRowOptions getOptions, WriteOptions writeOptions)`
  Deletes multiple rows from a table in an atomic operation, returning a future to manage the asynchronous operation.
  `List<Row>`
  `multiGet(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)`
  Returns the rows associated with a partial primary key in an atomic manner.
  `CompletableFuture<List<Row>>`
  `multiGetAsync(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)`
  Returns the rows associated with a partial primary key in an atomic manner, returning a future to manage the asynchronous operation.
  `List<PrimaryKey>`
  `multiGetKeys(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)`
  Return the keys associated with a partial primary key in an atomic manner.
  `CompletableFuture<List<PrimaryKey>>`
  `multiGetKeysAsync(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)`
  Return the keys associated with a partial primary key in an atomic manner, returning a future to manage the asynchronous operation.
  `void`
  `put(List<EntryStream<Row>> streams, BulkWriteOptions bulkWriteOptions)`
  Loads rows supplied by special purpose streams into the store.
  `Version`
  `put(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table.
  `CompletableFuture<Version>`
  `putAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table, returning a future to manage the asynchronous operation.
  `Version`
  `putIfAbsent(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table, but only if the row does not exist.
  `CompletableFuture<Version>`
  `putIfAbsentAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table, but only if the row does not exist, returning a future to manage the asynchronous operation.
  `Version`
  `putIfPresent(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table, but only if the row already exists.
  `CompletableFuture<Version>`
  `putIfPresentAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row into a table, but only if the row already exists, returning a future to manage the asynchronous operation.
  `Version`
  `putIfVersion(Row row, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row, but only if the version of the existing row matches the matchVersion argument.
  `CompletableFuture<Version>`
  `putIfVersionAsync(Row row, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)`
  Puts a row, but only if the version of the existing row matches the `matchVersion` argument, returning a future to manage the asynchronous operation.
  `TableIterator<Row>`
  `tableIterator(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `TableIterator<Row>`
  `tableIterator(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `TableIterator<Row>`
  `tableIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the rows associated with an index key.
  `TableIterator<Row>`
  `tableIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the rows associated with a partial primary key.
  `Publisher<Row>`
  `tableIteratorAsync(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `Publisher<Row>`
  `tableIteratorAsync(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `Publisher<Row>`
  `tableIteratorAsync(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows associated with an index key.
  `Publisher<Row>`
  `tableIteratorAsync(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows associated with a partial primary key.
  `TableIterator<PrimaryKey>`
  `tableKeysIterator(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `TableIterator<PrimaryKey>`
  `tableKeysIterator(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `TableIterator<KeyPair>`
  `tableKeysIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Return the keys for matching rows associated with an index key.
  `TableIterator<PrimaryKey>`
  `tableKeysIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns an iterator over the keys associated with a partial primary key.
  `Publisher<PrimaryKey>`
  `tableKeysIteratorAsync(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `Publisher<PrimaryKey>`
  `tableKeysIteratorAsync(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).
  `Publisher<KeyPair>`
  `tableKeysIteratorAsync(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys for matching rows associated with an index key.
  `Publisher<PrimaryKey>`
  `tableKeysIteratorAsync(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)`
  Returns a publisher that can be used to subscribe to the results an asynchronous iteration over the keys associated with a partial primary key.

- ## Field Details

  - ### SYSDEFAULT_NAMESPACE_NAME

    static final String SYSDEFAULT_NAMESPACE_NAME
    Name of "sysdefault" namespace. This namespace exists in a new store.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### execute

    @Deprecated ExecutionFuture execute(String statement) throws IllegalArgumentException, KVSecurityException, FaultException
    Deprecated.
    since 3.3 in favor of `KVStore.execute(String)`
    Asynchronously executes a table statement. Currently, table statements can be used to create or modify tables and indices. The operation is asynchronous and may not be finished when the method returns.

    An `ExecutionFuture` instance is returned which extends `Future` and can be used to get information about the status of the operation, or to await completion of the operation.

    For example:

         // Create a table
         ExecutionFuture future = null;
         try {
             future = tableAPI.execute
                  ("CREATE TABLE users (" +
                   "id INTEGER, " +
                   "firstName STRING, " +
                   "lastName STRING, " +
                   "age INTEGER, " +
                   "PRIMARY KEY (id))");
         } catch (IllegalArgumentException e) {
             System.out.println("The statement is invalid: " + e);
         } catch (FaultException e) {
             System.out.println("There is a transient problem, retry the " +
                                  "operation: " + e);
         }
         // Wait for the operation to finish
         StatementResult result = future.get()

    If the statement is a data definition or administrative operation, and the store is currently executing an operation that is the logical equivalent of the action specified by the statement, the method will return an ExecutionFuture that serves as a handle to that operation, rather than starting a new invocation of the command. The caller can use the ExecutionFuture to await the completion of the operation.

           // process A starts an index creation
           ExecutionFuture futureA =
               tableAPI.execute("CREATE INDEX age ON users(age)");

           // process B starts the same index creation. If the index creation is
           // still running in the cluster, futureA and futureB will refer to
           // the same operation
           ExecutionFuture futureB =
               tableAPI.execute("CREATE INDEX age ON users(age)");

    Note that, in a secure store, creating and modifying table and index definitions may require a level of system privileges over and beyond that required for reads and writes of table records.
    See the Data Definition Language for Tables guide in the documentation for information about supported statements.

    Parameters:
      `statement` - must follow valid Table syntax.
    Throws:
      `IllegalArgumentException` - if the statement is not valid
      `KVSecurityException` - if the operation fails due to a failure in authorization or authentication.
      `FaultException` - if the statement cannot be completed. This indicates a transient problem with communication to the server or within the server, and the statement can be retried.
    Since:
      3.2

  - ### executeSync

    @Deprecated StatementResult executeSync(String statement)
    Deprecated.
    since 3.3 in favor of `KVStore.executeSync(java.lang.String)`
    Synchronously execute a table statement. The method will only return when the statement has finished. Has the same semantics as `execute(String)`, but offers synchronous behavior as a convenience. ExecuteSync() is the equivalent of:

         ExecutionFuture future = tableAPI.execute( ... );
         return future.get();

    When executeSync() returns, statement execution will have terminated, and the resulting `StatementResult` will provide information about the outcome.
    Parameters:
      `statement` - must follow valid Table syntax.
    Throws:
      `IllegalArgumentException` - if the statement is not valid
    Since:
      3.2
    See Also:
      - `execute(String)`
      - Read exceptions
      - Write exceptions

  - ### getTable

    Table getTable(String fullNamespaceName)
    Gets an instance of a table. This method can be retried in the event that the specified table is not yet fully initialized. This call will typically go to a server node to find the requested metadata and/or verify that it is current.

    This interface will only retrieve top-level tables -- those with no parent table. Child tables are retrieved using `Table.getChildTable(java.lang.String)`.

    Parameters:
      `fullNamespaceName` - the full name or namespace qualified name of the target table. If an unqualified name is used then the "sysdefault" namespace will be used. If fullNamespaceName specifies a namespace followed by a colon before specifying the full name, then that is equivalent to calling `getTable(String, String)` with the namespace and full name.
    Returns:
      the table or null if the table does not exist
    See Also:
      - Read exceptions

  - ### getTable

    Table getTable(String namespace, String tableFullName)
    Gets an instance of a table. This method can be retried in the event that the specified table is not yet fully initialized. This call will typically go to a server node to find the requested metadata and/or verify that it is current.

    This interface will only retrieve top-level tables -- those with no parent table. Child tables are retrieved using `Table.getChildTable(java.lang.String)`.

    Parameters:
      `namespace` - the namespace of the target table. If null, the "sysdefault" `SYSDEFAULT_NAMESPACE_NAME` namespace will be used and the result is the same as calling the single argument method.
      `tableFullName` - the full name of the target table
    Returns:
      the table or null if the table does not exist
    Since:
      18.3
    See Also:
      - Read exceptions

  - ### getTables

    Map<String,Table> getTables()
    Gets all known tables. Only top-level tables -- those without parent tables -- are returned. Child tables of a parent are retrieved using `Table.getChildTables()`.
    Returns:
      the map of tables. If there are no tables an empty map is returned.
    See Also:
      - Read exceptions

  - ### getTables

    Map<String,Table> getTables(String namespace)
    Gets all known tables in the specified namespace. Only top-level tables -- those without parent tables -- are returned. Child tables of a parent are retrieved using `Table.getChildTables()`.
    Parameters:
      `namespace` - the namespace to use. If null, the initial `SYSDEFAULT_NAMESPACE_NAME` namespace will be used.
    Returns:
      the map of tables. The String keys have the namespace removed. If there are no tables an empty map is returned.
    Since:
      18.3
    See Also:
      - Read exceptions

  - ### listNamespaces

    Set<String> listNamespaces() throws FaultException
    Gets all known namespaces.
    Returns:
      the set of namespaces. If no metadata is available returns an empty collection, otherwise returns a set containing at least the "sysdefault" namespace. `SYSDEFAULT_NAMESPACE_NAME`.
    Throws:
      `FaultException`
    Since:
      18.3
    See Also:
      - Read exceptions

  - ### get

    Row get(PrimaryKey key, ReadOptions readOptions)
    Gets the `Row` associated with the primary key.
    Parameters:
      `key` - the primary key for a table. It must be a complete primary key, with all fields set.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      the matching row, or `null` if not found
    Throws:
      `IllegalArgumentException` - if the primary key is not complete
    See Also:
      - Read exceptions

  - ### getAsync

    CompletableFuture<Row> getAsync(PrimaryKey key, ReadOptions readOptions)
    Gets the `Row` associated with the primary key, returning a future to manage the asynchronous operation.

    The result supplied to the future is the matching row, or `null` if not found.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is not complete
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the primary key for a table. It must be a complete primary key, with all fields set.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### multiGet

    List<Row> multiGet(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)
    Returns the rows associated with a partial primary key in an atomic manner. Rows are returned in primary key order. The key used must contain all of the fields defined for the table's shard key.
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      a list of matching rows, one for each selected record, or an empty list if no rows are matched
    Throws:
      `IllegalArgumentException` - if the primary key is malformed or does not contain the required fields
    See Also:
      - Read exceptions

  - ### multiGetAsync

    CompletableFuture<List<Row>> multiGetAsync(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)
    Returns the rows associated with a partial primary key in an atomic manner, returning a future to manage the asynchronous operation.

    Rows are returned in primary key order. The key used must contain all of the fields defined for the table's shard key.

    The result supplied to the future is a list of matching rows, one for each selected record, or an empty list if no rows are matched.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed or does not contain the required fields
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### multiGetKeys

    List<PrimaryKey> multiGetKeys(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)
    Return the keys associated with a partial primary key in an atomic manner. Keys are returned in primary key order. The key used must contain all of the fields defined for the table's shard key.
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      a list of matching keys, one for each selected row, or an empty list if no rows are matched
    Throws:
      `IllegalArgumentException` - if the primary key is malformed or does not contain the required fields
    See Also:
      - Read exceptions

  - ### multiGetKeysAsync

    CompletableFuture<List<PrimaryKey>> multiGetKeysAsync(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions)
    Return the keys associated with a partial primary key in an atomic manner, returning a future to manage the asynchronous operation.

    Keys are returned in primary key order. The key used must contain all of the fields defined for the table's shard key.

    The result supplied to the future is a list of matching keys, one for each selected row, or an empty list if no rows are matched.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed or does not contain the required fields
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `readOptions` - non-default options for the operation or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableIterator

    TableIterator<Row> tableIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the rows associated with a partial primary key.
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete shard key. If the key contains a partial shard key the iteration goes to all partitions in the store. If the key contains a complete shard key the operation is restricted to the target partition. If the key has no fields set the entire table is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. If the primary key contains a complete shard key, the default Direction in `TableIteratorOptions` is `Direction.FORWARD`. Otherwise, the default Direction in `TableIteratorOptions` is `Direction.UNORDERED`.
    Returns:
      an iterator over the matching rows, or an empty iterator if none match. If the primary key contains a complete shard key, the methods on TableIterator associated with `ParallelScanIterator`, such as statistics, will not return meaningful information because the iteration will be single-partition and not parallel.
    Throws:
      `IllegalArgumentException` - if the primary key is malformed or an invalid option is specified, such as iteration order without a complete shard key.
    See Also:
      - Read exceptions

  - ### tableIteratorAsync

    Publisher<Row> tableIteratorAsync(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows associated with a partial primary key. The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    The iteration returns the matching rows as results, or no results if no rows match. If the primary key contains a complete shard key, the methods on `IterationSubscription` that supply per-shard and per-partition metrics will not return meaningful information because the iteration will be single-partition and not parallel.

    If `Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)` is called more than once on the publisher, the `Subscriber.onError(java.lang.Throwable)` method will be called with an `IllegalStateException`.

    If the iteration fails, `Subscriber.onError(java.lang.Throwable)` will be called with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed or an invalid option is specified, such as iteration order without a complete shard key
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete shard key. If the key contains a partial shard key the iteration goes to all partitions in the store. If the key contains a complete shard key the operation is restricted to the target partition. If the key has no fields set the entire table is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. If the primary key contains a complete shard key, the default Direction in `TableIteratorOptions` is `Direction.FORWARD`. Otherwise, the default Direction in `TableIteratorOptions` is `Direction.UNORDERED`.
    Returns:
      a publisher for subscribing to the operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableKeysIterator

    TableIterator<PrimaryKey> tableKeysIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the keys associated with a partial primary key.
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete shard key. If the key contains a partial shard key the iteration goes to all partitions in the store. If the key contains a complete shard key the operation is restricted to the target partition. If the key has no fields set the entire table is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. If the primary key contains a complete shard key, the default Direction in `TableIteratorOptions` is `Direction.FORWARD`. Otherwise, the default Direction in `TableIteratorOptions` is `Direction.UNORDERED`.
    Returns:
      an iterator over the primary keys of matching rows, or an empty iterator if none match. If the primary key contains a complete shard key, the methods on TableIterator associated with `ParallelScanIterator`, such as statistics, will not return meaningful information because the iteration will be single-partition and not parallel.
    Throws:
      `IllegalArgumentException` - if the primary key is malformed or an invalid option is specified, such as iteration order without a complete shard key
    See Also:
      - Read exceptions

  - ### tableKeysIteratorAsync

    Publisher<PrimaryKey> tableKeysIteratorAsync(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results an asynchronous iteration over the keys associated with a partial primary key. The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    The iteration returns the primary keys of matching rows as results, or no results if no rows match. If the primary key contains a complete shard key, the methods on `IterationSubscription` that supply per-shard and per-partition metrics will not return meaningful information because the iteration will be single-partition and not parallel.

    If `Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)` is called more than once on the publisher, the `Subscriber.onError(java.lang.Throwable)` method will be called with an `IllegalStateException`.

    If the iteration fails, `Subscriber.onError(java.lang.Throwable)` will be called with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed or an invalid option is specified, such as iteration order without a complete shard key
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the primary key for the operation. It may be partial or complete shard key. If the key contains a partial shard key the iteration goes to all partitions in the store. If the key contains a complete shard key the operation is restricted to the target partition. If the key has no fields set the entire table is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. If the primary key contains a complete shard key, the default Direction in `TableIteratorOptions` is `Direction.FORWARD`. Otherwise, the default Direction in `TableIteratorOptions` is `Direction.UNORDERED`.
    Returns:
      a publisher for subscribing to the operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableIterator

    TableIterator<Row> tableIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the rows associated with an index key. This method requires an additional database read on the server side to get row information for matching rows. Ancestor table rows for matching index rows may be returned as well if specified in the `getOptions` parameter. Index operations may not specify the return of child table rows.
    Parameters:
      `key` - the index key for the operation. It may be partial or complete. If the key has no fields set the entire index is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table on which the index is defined is always included as a target. Child tables cannot be included for index operations.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. The default Direction in `TableIteratorOptions` is `Direction.FORWARD`.
    Returns:
      an iterator over the matching rows, or an empty iterator if none match
    Throws:
      `IllegalArgumentException` - if the primary key is malformed
      `UnsupportedOperationException` - if the `getOptions` parameter specifies the return of child tables
    See Also:
      - Read exceptions

  - ### tableIteratorAsync

    Publisher<Row> tableIteratorAsync(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows associated with an index key. The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    This method requires an additional database read on the server side to get row information for matching rows. Ancestor table rows for matching index rows may be returned as well if specified in the `getOptions` parameter. Index operations may not specify the return of child table rows.

    The iteration returns the matching rows as results, or no results if no rows match.

    If `Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)` is called more than once on the publisher, the `Subscriber.onError(java.lang.Throwable)` method will be called with an `IllegalStateException`.

    If the iteration fails, `Subscriber.onError(java.lang.Throwable)` will be called with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed
    - `UnsupportedOperationException` - if the `getOptions` parameter specifies the return of child tables
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the index key for the operation. It may be partial or complete. If the key has no fields set the entire index is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table on which the index is defined is always included as a target. Child tables cannot be included for index operations.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. The default Direction in `TableIteratorOptions` is `Direction.FORWARD`.
    Returns:
      a publisher for subscribing to the operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableKeysIterator

    TableIterator<KeyPair> tableKeysIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Return the keys for matching rows associated with an index key. The iterator returned only references information directly available from the index. No extra fetch operations are performed. Ancestor table keys for matching index keys may be returned as well if specified in the `getOptions` parameter. Index operations may not specify the return of child table keys.
    Parameters:
      `key` - the index key for the operation. It may be partial or complete. If the key has no fields set the entire index is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table on which the index is defined is always included as a target. Child tables cannot be included for index operations.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. The default Direction in `TableIteratorOptions` is `Direction.FORWARD`.
    Returns:
      an iterator over `KeyPair` objects, which provide access to both the `PrimaryKey` associated with a match as well as the values in the matching `IndexKey` without an additional fetch of the Row itself.
    Throws:
      `IllegalArgumentException` - if the primary key is malformed
      `UnsupportedOperationException` - if the `getOptions` parameter specifies the return of child tables
    See Also:
      - Read exceptions

  - ### tableKeysIteratorAsync

    Publisher<KeyPair> tableKeysIteratorAsync(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys for matching rows associated with an index key. The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    The iteration only references information directly available from the index. No extra fetch operations are performed. Ancestor table keys for matching index keys may be returned as well if specified in the `getOptions` parameter. Index operations may not specify the return of child table keys.

    The iteration returns `KeyPair` objects as results, which provide access to both the `PrimaryKey` associated with a match as well as the values in the matching `IndexKey` without an additional fetch of the Row itself.

    If `Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)` is called more than once on the publisher, the `Subscriber.onError(java.lang.Throwable)` method will be called with an `IllegalStateException`.

    If the iteration fails, `Subscriber.onError(java.lang.Throwable)` will be called with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed
    - `UnsupportedOperationException` - if the `getOptions` parameter specifies the return of child tables
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `key` - the index key for the operation. It may be partial or complete. If the key has no fields set the entire index is matched.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table on which the index is defined is always included as a target. Child tables cannot be included for index operations.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. The default Direction in `TableIteratorOptions` is `Direction.FORWARD`.
    Returns:
      a publisher for subscribing to the operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableIterator

    TableIterator<Row> tableIterator(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).

    The result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of rows in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth. Batches are fetched in parallel across multiple Replication Nodes, the degree of parallelism is controlled by the TableIteratorOptions argument.

    Parameters:
      `primaryKeyIterator` - it yields a sequence of primary keys, the primary key may be partial or complete, it must contain all of the fields defined for the table's shard key. The iterator implementation need not be thread-safe.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. Currently, the Direction in `TableIteratorOptions` can only be `Direction.UNORDERED`, others are not supported.
    Returns:
      an iterator over the matching rows. If the `primaryKeyIterator` yields duplicate keys, the row associated with the duplicate keys will be returned at least once and potentially multiple times. The implementation makes an effort to minimize these duplicate values but the exact number of repeated rows is not defined by the implementation, since weeding out such duplicates can be resource intensive.
    Throws:
      `IllegalArgumentException` - if the supplied key iterator is `null` or invalid option is specified, such as unsupported iteration order
    Since:
      3.4
    See Also:
      - Read exceptions

  - ### tableIteratorAsync

    Publisher<Row> tableIteratorAsync(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument). The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    The result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of rows in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth. Batches are fetched in parallel across multiple Replication Nodes, the degree of parallelism is controlled by the TableIteratorOptions argument.

    The iteration returns the matching rows as results. If the `primaryKeyIterator` yields duplicate keys, the row associated with the duplicate keys will be returned at least once and potentially multiple times. The implementation makes an effort to minimize these duplicate values but the exact number of repeated rows is not defined by the implementation, since weeding out such duplicates can be resource intensive.

    If `Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)` is called more than once on the publisher, the `Subscriber.onError(java.lang.Throwable)` method will be called with an `IllegalStateException`.

    If the iteration fails, `Subscriber.onError(java.lang.Throwable)` will be called with one of the following exceptions:

    - `IllegalArgumentException` - if the supplied key iterator is `null` or invalid option is specified, such as unsupported iteration order
    - `FaultException` - for one of the standard read exceptions
    Parameters:
      `primaryKeyIterator` - it yields a sequence of primary keys, the primary key may be partial or complete, it must contain all of the fields defined for the table's shard key. The iterator implementation need not be thread-safe.
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the results. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `iterateOptions` - the non-default arguments for consistency of the operation and to control the iteration or `null` to get default behavior. Currently, the Direction in `TableIteratorOptions` can only be `Direction.UNORDERED`, others are not supported.
    Returns:
      a publisher for subscribing to the operation
    Since:
      19.5
    See Also:
      - Read exceptions
      - Thread model for asynchronous execution

  - ### tableKeysIterator

    TableIterator<PrimaryKey> tableKeysIterator(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions) throws ConsistencyException, RequestTimeoutException, KVSecurityException, FaultException
    Returns an iterator over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).

    This method is almost identical to `tableIterator(Iterator, MultiRowOptions, TableIteratorOptions)` but differs solely in the type of its return value (PrimaryKeys instead of rows).

    Throws:
      `ConsistencyException`
      `RequestTimeoutException`
      `KVSecurityException`
      `FaultException`
    Since:
      3.4
    See Also:
      - `tableIterator(Iterator, MultiRowOptions, TableIteratorOptions)`

  - ### tableKeysIteratorAsync

    Publisher<PrimaryKey> tableKeysIteratorAsync(Iterator<PrimaryKey> primaryKeyIterator, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument). The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    This method is almost identical to `tableIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)` but differs solely in the type of its return value (PrimaryKeys instead of rows).

    Since:
      19.5
    See Also:
      - `tableIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)`
      - Thread model for asynchronous execution

  - ### tableIterator

    TableIterator<Row> tableIterator(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).

    Except for the difference in the type of the first argument: `primaryKeyIterators`, which is a list of iterators instead of a single iterator, this method is identical to the overloaded `tableIterator(Iterator, MultiRowOptions, TableIteratorOptions)` method. One or more of the iterators in the `primaryKeyIterators` list may be read in parallel to maximize input throughput, the element of key iterator list should be non-`null`.

    Since:
      3.4
    See Also:
      - Read exceptions
      - `tableIterator(Iterator, MultiRowOptions, TableIteratorOptions)`

  - ### tableIteratorAsync

    Publisher<Row> tableIteratorAsync(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the rows matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument). The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    Except for the difference in the type of the first argument, `primaryKeyIterators`, which is a list of iterators instead of a single iterator, this method is identical to the overloaded `tableIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)` method. One or more of the iterators in the `primaryKeyIterators` list may be read in parallel to maximize input throughput, the element of key iterator list should be non-`null`.

    Since:
      19.5
    See Also:
      - Read exceptions
      - `tableIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)`
      - Thread model for asynchronous execution

  - ### tableKeysIterator

    TableIterator<PrimaryKey> tableKeysIterator(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns an iterator over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument).

    Except for the difference in the type of the first argument: `primaryKeyIterators`, which is a list of iterators instead of a single iterator, this method is identical to the overloaded `tableKeysIterator(Iterator, MultiRowOptions, TableIteratorOptions)` method. One or more of the iterators in the `primaryKeyIterators` list may be read in parallel to maximize input throughput, the element of key iterator list should be non-`null`.

    Since:
      3.4
    See Also:
      - Read exceptions
      - `tableKeysIterator(Iterator, MultiRowOptions, TableIteratorOptions)`

  - ### tableKeysIteratorAsync

    Publisher<PrimaryKey> tableKeysIteratorAsync(List<Iterator<PrimaryKey>> primaryKeyIterators, MultiRowOptions getOptions, TableIteratorOptions iterateOptions)
    Returns a publisher that can be used to subscribe to the results of an asynchronous iteration over the keys matching the primary keys supplied by iterator (or the rows in ancestor or descendant tables, or those in a range specified by the MultiRowOptions argument). The subscription supplied to the subscriber will implement `IterationSubscription`. The publisher may only be used for a single subscription.

    Except for the difference in the type of the first argument, `primaryKeyIterators`, which is a list of iterators instead of a single iterator, this method is identical to the overloaded `tableKeysIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)` method. One or more of the iterators in the `primaryKeyIterators` list may be read in parallel to maximize input throughput, the element of key iterator list should be non-`null`.

    Since:
      19.5
    See Also:
      - Read exceptions
      - `tableKeysIteratorAsync(Iterator, MultiRowOptions, TableIteratorOptions)`
      - Thread model for asynchronous execution

  - ### put

    Version put(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table. The row must contain a complete primary key and all required fields.

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, the version in this object is set to `null` and none of the row's fields are available.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior. See `WriteOptions` for more information.
    Returns:
      the version of the new row value
    Throws:
      `IllegalArgumentException` - if the row does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### putAsync

    CompletableFuture<Version> putAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table, returning a future to manage the asynchronous operation. The row must contain a complete primary key and all required fields.

    The result supplied to the future is the version of the new row value.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the row does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, the version in this object is set to `null` and none of the row's fields are available.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior. See `WriteOptions` for more information.
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### putIfAbsent

    Version putIfAbsent(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table, but only if the row does not exist. The row must contain a complete primary key and all required fields.

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available. This object will only be initialized if the operation fails because of an existing row.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      the version of the new value, or `null` if an existing value is present and the put is unsuccessful
    Throws:
      `IllegalArgumentException` - if the row does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### putIfAbsentAsync

    CompletableFuture<Version> putIfAbsentAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table, but only if the row does not exist, returning a future to manage the asynchronous operation. The row must contain a complete primary key and all required fields.

    The result supplied to the future is the version of the new value, or `null` if an existing value is present and the put is unsuccessful. If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the row does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available. This object will only be initialized if the operation fails because of an existing row.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### putIfPresent

    Version putIfPresent(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table, but only if the row already exists. The row must contain a complete primary key and all required fields.

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call. When the GENERATED ALWAYS IDENTITY column is part of the primary key a value is generated only if one is not set, this way existing rows can be updated.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      the version of the new value, or `null` if there is no existing row and the put is unsuccessful
    Throws:
      `IllegalArgumentException` - if the `Row` does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### putIfPresentAsync

    CompletableFuture<Version> putIfPresentAsync(Row row, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row into a table, but only if the row already exists, returning a future to manage the asynchronous operation. The row must contain a complete primary key and all required fields.

    The result supplied to the future is the version of the new value, or `null` if there is no existing row and the put is unsuccessful.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the `Row` does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call. When the GENERATED ALWAYS IDENTITY column is part of the primary key a value is generated only if one is not set, this way existing rows can be updated.

    Parameters:
      `row` - the row to put
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available.

      If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.

      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### putIfVersion

    Version putIfVersion(Row row, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row, but only if the version of the existing row matches the matchVersion argument. Used when updating a value to ensure that it has not changed since it was last read. The row must contain a complete primary key and all required fields.

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `matchVersion` - the version to match
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available. This object will only be initialized if the operation fails with a version mismatch. If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      the version of the new value, or `null` if the versions do not match and the put is unsuccessful
    Throws:
      `IllegalArgumentException` - if the `Row` does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### putIfVersionAsync

    CompletableFuture<Version> putIfVersionAsync(Row row, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)
    Puts a row, but only if the version of the existing row matches the `matchVersion` argument, returning a future to manage the asynchronous operation. Used when updating a value to ensure that it has not changed since it was last read. The row must contain a complete primary key and all required fields.

    The result supplied to the future is the version of the new value, or `null` if the versions do not match and the put is unsuccessful.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the `Row` does not have a complete primary key or is otherwise invalid, or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions

    For tables that contain IDENTITY columns, the call generates the next value in the sequence. The value is generated on the client, from a pool of values controlled by the CACHE size option or by `WriteOptions.setIdentityCacheSize(int)`. An extra call to the server is made only to refresh the pool of values. The generated value is updated, as a side effect, in the row object after this call. For an IDENTITY GENERATED BY DEFAULT column, if row doesn't contain a value (or null for ON NULL option) a new value is generated, otherwise the user specified value is used for the call.

    Parameters:
      `row` - the row to put
      `matchVersion` - the version to match
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that nothing should be returned, the version in this object is set to `null` and none of the row's fields are available. This object will only be initialized if the operation fails with a version mismatch. If a non-`null` `ReturnRow` is specified and a previous row exists, then the expiration time of the previous row can be accessed by calling `getExpirationTime()` on `prevRow`.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### delete

    boolean delete(PrimaryKey key, ReturnRow prevRow, WriteOptions writeOptions)
    Deletes a row from a table.
    Parameters:
      `key` - the primary key for the row to delete
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, the version in this object is set to `null` and none of the row's fields are available.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      `true` if the row existed and was deleted, and `false` otherwise
    Throws:
      `IllegalArgumentException` - if the primary key is not complete or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### deleteAsync

    CompletableFuture<Boolean> deleteAsync(PrimaryKey key, ReturnRow prevRow, WriteOptions writeOptions)
    Deletes a row from a table, returning a future to manage the asynchronous operation.

    The result supplied to the future is `true` if the row existed and was deleted, and `false` otherwise.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is not complete or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions
    Parameters:
      `key` - the primary key for the row to delete
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, the version in this object is set to `null` and none of the row's fields are available.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### deleteIfVersion

    boolean deleteIfVersion(PrimaryKey key, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)
    Deletes a row from a table but only if its version matches the one specified in matchVersion.
    Parameters:
      `key` - the primary key for the row to delete
      `matchVersion` - the version to match
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, or the matchVersion parameter matches the existing value and the delete is successful, the version in this object is set to `null` and none of the row's fields are available.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      `true` if the row existed, and its version matched `matchVersion` and was successfully deleted, and `false` otherwise
    Throws:
      `IllegalArgumentException` - if the primary key is not complete or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### deleteIfVersionAsync

    CompletableFuture<Boolean> deleteIfVersionAsync(PrimaryKey key, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions)
    Deletes a row from a table, but only if its version matches the one specified in `matchVersion`, returning a future to manage the asynchronous operation.

    The result supplied to the future is `true` if the row existed, and its version matched `matchVersion` and was successfully deleted, and `false` otherwise.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is not complete or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions
    Parameters:
      `key` - the primary key for the row to delete
      `matchVersion` - the version to match
      `prevRow` - a `ReturnRow` object to contain the previous row value and version associated with the given row, or `null` if they should not be returned. If a previous row does not exist, or the `ReturnRow.Choice` specifies that they should not be returned, or the matchVersion parameter matches the existing value and the delete is successful, the version in this object is set to `null` and none of the row's fields are available.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### multiDelete

    int multiDelete(PrimaryKey key, MultiRowOptions getOptions, WriteOptions writeOptions)
    Deletes multiple rows from a table in an atomic operation. The key used may be partial but must contain all the fields that are in the shard key.
    Parameters:
      `key` - the primary key for the row to delete
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the operation. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      the number of rows deleted from the table
    Throws:
      `IllegalArgumentException` - if the primary key is malformed or does not contain all shard key fields or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    See Also:
      - Write exceptions

  - ### multiDeleteAsync

    CompletableFuture<Integer> multiDeleteAsync(PrimaryKey key, MultiRowOptions getOptions, WriteOptions writeOptions)
    Deletes multiple rows from a table in an atomic operation, returning a future to manage the asynchronous operation. The key used may be partial but must contain all the fields that are in the shard key.

    The result supplied to the future is the number of rows deleted from the table.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `IllegalArgumentException` - if the primary key is malformed or does not contain all shard key fields or if `Row.setRowMetadata(String)` is not a valid JSON construct.
    - `FaultException` - for one of the standard write exceptions
    Parameters:
      `key` - the primary key for the row to delete
      `getOptions` - a `MultiRowOptions` object used to control ranges in the operation and whether ancestor and descendant tables are included in the operation. It may be `null`. The table used to construct the `PrimaryKey` parameter is always included as a target.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### getTableOperationFactory

    TableOperationFactory getTableOperationFactory()
    Returns a `TableOperationFactory` to create operations passed to `execute(java.lang.String)`. Not all operations must use the same table, but they must all use the same shard portion of the primary key.
    Returns:
      an empty `TableOperationFactory`

  - ### execute

    List<TableOperationResult> execute(List<TableOperation> operations, WriteOptions writeOptions) throws TableOpExecutionException
    This method provides an efficient and transactional mechanism for executing a sequence of operations associated with tables that share the same shard key portion of their primary keys. The efficiency results from the use of a single network interaction to accomplish the entire sequence of operations. If the underlying store instance has only one partition, as is the case with `KVLocal` the shared shard key constraint is relaxed as in that environment all keys can be accessed in a single transaction.

    The operations passed to this method are created using an `TableOperationFactory`, which is obtained from the `getTableOperationFactory()` method.

    All the `operations` specified are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this method. If the method returns without throwing an exception, then all operations were executed atomically, the transaction was committed, and the returned list contains the result of each operation.

    If the transaction is aborted for any reason, an exception is thrown. An abort may occur for two reasons:

    1. An operation or transaction results in an exception that is considered a fault, such as a durability or consistency error, a failure due to message delivery or networking error, etc. A `FaultException` is thrown.
    2. An individual operation returns normally but is unsuccessful as defined by the particular operation (e.g., a delete operation for a non-existent key) and `true` was passed for the `abortIfUnsuccessful` parameter when the operation was created using the `TableOperationFactory`. A `TableOpExecutionException` is thrown, and the exception contains information about the failed operation.

    Operations are not executed in the sequence they appear the `operations` list, but are rather executed in an internally defined sequence that prevents deadlocks. Additionally, if there are two operations for the same key, their relative order of execution is arbitrary; this should be avoided.

    Parameters:
      `operations` - the list of operations to be performed. Note that all operations in the list must specify primary keys with the same complete shard key unless the store has a single partition.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      the sequence of results associated with the operation. There is one entry for each TableOperation in the operations argument list. The returned list is in the same order as the operations argument list.
    Throws:
      `TableOpExecutionException` - if an operation is not successful as defined by the particular operation (e.g., a delete operation for a non-existent key) and `true` was passed for the `abortIfUnsuccessful` parameter when the operation was created using the `TableOperationFactory`
      `IllegalArgumentException` - if operations is `null` or empty, or not all operations operate on primary keys with the same shard key and the store is not single partition, or more than one operation has the same primary key, or any of the primary keys are incomplete
    See Also:
      - Write exceptions

  - ### executeAsync

    CompletableFuture<List<TableOperationResult>> executeAsync(List<TableOperation> operations, WriteOptions writeOptions)
    This method provides an efficient and transactional mechanism for executing a sequence of operations associated with tables that share the same shard key portion of their primary keys, returning a future to manage the asynchronous operation. The efficiency results from the use of a single network interaction to accomplish the entire sequence of operations. If the underlying store instance has only one partition, as is the case with `KVLocal` the shared shard key constraint is relaxed as in that environment all keys can be accessed in a single transaction.

    The operations passed to this method are created using an `TableOperationFactory`, which is obtained from the `getTableOperationFactory()` method.

    All the `operations` specified are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this method. If the method completes normally by supplying a result to the future, then all operations were executed atomically, the transaction was committed, and the result list contains the result of each operation.

    If the transaction is aborted for any reason, the future will complete exceptionally. An abort may occur for two reasons:

    1. An operation or transaction results in an exception that is considered a fault, such as a durability or consistency error, a failure due to message delivery or networking error, etc. A `FaultException` is thrown.
    2. An individual operation returns normally but is unsuccessful as defined by the particular operation (e.g., a delete operation for a non-existent key) and `true` was passed for the `abortIfUnsuccessful` parameter when the operation was created using the `TableOperationFactory`. A `TableOpExecutionException` is thrown, and the exception contains information about the failed operation.

    Operations are not executed in the sequence they appear the `operations` list, but are rather executed in an internally defined sequence that prevents deadlocks. Additionally, if there are two operations for the same key, their relative order of execution is arbitrary; this should be avoided.

    The result supplied to the future is the sequence of results associated with the operation. There is one entry for each TableOperation in the operations argument list. The result list is in the same order as the operations argument list.

    If the request fails, the future will complete exceptionally with one of the following exceptions:

    - `TableOpExecutionException` - if an operation is not successful as defined by the particular operation (e.g., a delete operation for a non-existent key) and `true` was passed for the `abortIfUnsuccessful` parameter when the operation was created using the `TableOperationFactory`
    - `IllegalArgumentException` - if operations is `null` or empty, or not all operations operate on primary keys with the same shard key and the store is not single partition, or more than one operation has the same primary key, or any of the primary keys are incomplete
    - `FaultException` - for one of the standard write exceptions
    Parameters:
      `operations` - the list of operations to be performed. Note that all operations in the list must specify primary keys with the same complete shard key unless the store has a single partition.
      `writeOptions` - non-default arguments controlling the durability of the operation, or `null` to get default behavior
    Returns:
      a future for managing the asynchronous operation
    Since:
      19.5
    See Also:
      - Write exceptions
      - Thread model for asynchronous execution

  - ### put

    void put(List<EntryStream<Row>> streams, BulkWriteOptions bulkWriteOptions)
    Loads rows supplied by special purpose streams into the store. The bulk loading of the entries is optimized to make efficient use of hardware resources. As a result, this operation can achieve much higher throughput when compared with single row put APIs.

    Entries are supplied to the loader by a list of EntryStream instances. Each stream is read sequentially, that is, each EntryStream.getNext() is allowed to finish before the next operation is issued. The load operation typically reads from these streams in parallel as determined by `BulkWriteOptions.getStreamParallelism()`.

    If an entry is associated with a primary key that's already present in the store, the `EntryStream.keyExists(E)` method is invoked on it and the entry is not loaded into the store by this method; the `EntryStream.keyExists(E)` method may of course choose to do so itself, if the values differ.

    If the key is absent, a new entry is created in the store, that is, the load operation has putIfAbsent semantics. The putIfAbsent semantics permit restarting a load of a stream that failed for some reason.

    The collection of streams defines a partial insertion order, with insertion of rows containing the same shard key within a stream being strictly ordered, but with no ordering constraints being imposed on keys across streams, or for different keys within the same stream.

    The behavior of the bulk put operation with respect to duplicate entries contained in different streams is thus undefined. If the duplicate entries are just present in a single stream, then the first entry will be inserted (if it's not already present) and the second entry and subsequent entries will result in the invocation of the `EntryStream.keyExists(E)` method. If duplicates exist across streams, then the first entry to win the race is inserted and subsequent duplicates will result in `EntryStream.keyExists(E)` being invoked on them.

    Load operations tend to be long running. In order to facilitate resumption of such a long running operation due to a process or client machine failure, the application may use to checkpoint its progress at granularity of a stream, using the `EntryStream.completed()` method. The javadoc for this method provides further details.

    Exceptions encountered during the reading of streams result in the put operation being terminated and the first such exception being thrown from the put method.

    Exceptions encountered when inserting a row into the store result in the `EntryStream.catchException(java.lang.RuntimeException, E)` being invoked.

    Parameters:
      `streams` - the streams that supply the rows to be inserted. The rows within each stream may be associated with different tables. Elements of stream list must not be null.
      `bulkWriteOptions` - non-default arguments controlling the behavior the bulk write operations
    Since:
      4.0