Package oracle.kv.query

# Class ExecuteOptions

java.lang.Object
oracle.kv.query.ExecuteOptions

public class ExecuteOptions extends Object
Class contains several options for the execution of an SQL statement (DDL or DML). SQL statements are executed via one of the KVStore.execute() methods.

Since:
  4.0
See Also:
  - `KVStore.execute(String, ExecuteOptions)`
  - `KVStore.executeSync(String, ExecuteOptions)`
  - `KVStore.executeSync(Statement, ExecuteOptions)`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static short`
  `DRIVER_QUERY_V2`
  `static short`
  `DRIVER_QUERY_V3`
  `static long`
  `MAX_SERVER_MEMORY_CONSUMPTION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExecuteOptions()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Consistency`
  `getConsistency()`
  Gets the last set execution consistency.
  `Durability`
  `getDurability()`
  Gets the last set execution durability.
  `MathContext`
  `getMathContext()`
  Returns the `MathContext` used for `BigDecimal` and `BigInteger` operations.
  `int`
  `getMaxConcurrentRequests()`
  Returns the maximum number of concurrent requests.
  `long`
  `getMaxMemoryConsumption()`
  Get the maximum number of memory bytes that may be consumed by the statement at the client for blocking operations, such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting (sorting by distance when a query contains a geo_near() function).
  `String`
  `getNamespace()`
  Returns the namespace to use for the query, null if not set.
  `String`
  `getQueryName()`
  `int`
  `getResultsBatchSize()`
  Returns the number of results per request (see `setResultsBatchSize(int)`).
  `String`
  `getRowMetadata()`
  This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.
  `long`
  `getTimeout()`
  Gets the timeout, which is an upper bound on the time interval for processing the read or write operations.
  `TimeUnit`
  `getTimeoutUnit()`
  Gets the unit of the timeout parameter, and may be `null` only if `getTimeout()` returns zero.
  `int`
  `getUpdateLimit()`
  Returns the maximum number of records that can be updated in a single update query.
  `ExecuteOptions`
  `setConsistency(Consistency consistency)`
  Sets the execution consistency.
  `ExecuteOptions`
  `setDurability(Durability durability)`
  Sets the execution durability.
  `ExecuteOptions`
  `setMathContext(MathContext mathContext)`
  Sets the `MathContext` used for `BigDecimal` and `BigInteger` operations.
  `ExecuteOptions`
  `setMaxConcurrentRequests(int maxConcurrentRequests)`
  Sets the maximum number of concurrent requests.
  `void`
  `setMaxMemoryConsumption(long v)`
  Set the maximum number of memory bytes that may be consumed by the statement at the client for blocking operations, such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting (sorting by distance when a query contains a geo_near() function).
  `ExecuteOptions`
  `setNamespace(String namespace)`
  Sets the namespace to use for the query.
  `ExecuteOptions`
  `setQueryName(String n)`
  `ExecuteOptions`
  `setResultsBatchSize(int resultsBatchSize)`
  Sets the max number of query results to be generated during the execution of the query over a partition or shard (which takes place at a replication node (RN) that contains the target partition/shard).
  `ExecuteOptions`
  `setRowMetadata(String rowMetadata)`
  This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.
  `ExecuteOptions`
  `setTimeout(long timeout, TimeUnit timeoutUnit)`
  The `timeout` parameter is an upper bound on the time interval for processing one of the KVStore.execute(...) methods (`KVStore.execute(String, ExecuteOptions)`, `KVStore.executeSync(String, ExecuteOptions)`, or `KVStore.executeSync(Statement, ExecuteOptions)`) and any of the subsequent next() and hasNext() invocations of `StatementResult.iterator()`.
  `void`
  `setUpdateLimit(int limit)`
  Sets the maximum number of records that can be updated in a single update query.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DRIVER_QUERY_V2

    public static short DRIVER_QUERY_V2

  - ### DRIVER_QUERY_V3

    public static short DRIVER_QUERY_V3

  - ### MAX_SERVER_MEMORY_CONSUMPTION

    public static long MAX_SERVER_MEMORY_CONSUMPTION

- ## Constructor Details

  - ### ExecuteOptions

    public ExecuteOptions()

- ## Method Details

  - ### setConsistency

    public ExecuteOptions setConsistency(Consistency consistency)
    Sets the execution consistency.

  - ### getConsistency

    public Consistency getConsistency()
    Gets the last set execution consistency.

  - ### setDurability

    public ExecuteOptions setDurability(Durability durability)
    Sets the execution durability.

  - ### getDurability

    public Durability getDurability()
    Gets the last set execution durability.

  - ### setRowMetadata

    public ExecuteOptions setRowMetadata(String rowMetadata)
    This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions. Use with caution.

    Sets the row metadata to use for the operation. This setting only applies if the query modifies a row using an INSERT, UPDATE, UPSERT statement. If the query is read-only it is ignored. This is an optional parameter.

    Row metadata is associated to a certain version of a row. Any subsequent write operation will use its own row metadata value. If not specified null will be used by default. NOTE that if you have previously written a record with metadata and a subsequent write does not supply metadata, the metadata associated with the row will be null. Therefore, if you wish to have metadata associated with every write operation, you must supply a valid JSON construct to this method.

    Parameters:
      `rowMetadata` - the row metadata, must be null or in a valid JSON construct: object, array, string, number, true, false or null, otherwise an IllegalArgumentException is thrown.
    Returns:
      this
    Throws:
      `IllegalArgumentException` - if rowMetadata not null and invalid JSON Object format

  - ### getRowMetadata

    public String getRowMetadata()
    This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions. Use with caution.

    Returns the row metadata value set for this request, or null if not set.

    Returns:
      the row metadata value

  - ### setTimeout

    public ExecuteOptions setTimeout(long timeout, TimeUnit timeoutUnit)
    The `timeout` parameter is an upper bound on the time interval for processing one of the KVStore.execute(...) methods (`KVStore.execute(String, ExecuteOptions)`, `KVStore.executeSync(String, ExecuteOptions)`, or `KVStore.executeSync(Statement, ExecuteOptions)`) and any of the subsequent next() and hasNext() invocations of `StatementResult.iterator()`. Also, in case of asynchronous query execution (via `KVStore.executeAsync(String, ExecuteOptions)` or `KVStore.executeAsync(Statement, ExecuteOptions)`) is an upper bound on the time interval between two successive callbacks to the Subscriber instance used for the query execution. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.

    If `timeout` is not 0, the `timeoutUnit` parameter must not be `null`.

    Parameters:
      `timeout` - the timeout value to use
      `timeoutUnit` - the `TimeUnit` used by the `timeout` parameter or null

  - ### getTimeout

    public long getTimeout()
    Gets the timeout, which is an upper bound on the time interval for processing the read or write operations. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
    Returns:
      the timeout

  - ### getTimeoutUnit

    public TimeUnit getTimeoutUnit()
    Gets the unit of the timeout parameter, and may be `null` only if `getTimeout()` returns zero.
    Returns:
      the timeout unit or null

  - ### getMaxConcurrentRequests

    public int getMaxConcurrentRequests()
    Returns the maximum number of concurrent requests.

  - ### setMaxConcurrentRequests

    public ExecuteOptions setMaxConcurrentRequests(int maxConcurrentRequests)
    Sets the maximum number of concurrent requests.

  - ### getResultsBatchSize

    public int getResultsBatchSize()
    Returns the number of results per request (see `setResultsBatchSize(int)`).

  - ### setResultsBatchSize

    public ExecuteOptions setResultsBatchSize(int resultsBatchSize)
    Sets the max number of query results to be generated during the execution of the query over a partition or shard (which takes place at a replication node (RN) that contains the target partition/shard). If this max is reached, query execution at the RN stops and the generated batch of results is returned to the driver. If more results may be available at the same partition/shard, the driver will later send the query back to an RN that contains the target partition/shard and request another batch of results. The query will resume execution at the point where it got suspended during the previous batch.

  - ### getMathContext

    public MathContext getMathContext()
    Returns the `MathContext` used for `BigDecimal` and `BigInteger` operations. `MathContext.DECIMAL32` is used by default.

  - ### setMathContext

    public ExecuteOptions setMathContext(MathContext mathContext)
    Sets the `MathContext` used for `BigDecimal` and `BigInteger` operations. `MathContext.DECIMAL32` is used by default.

  - ### setNamespace

    public ExecuteOptions setNamespace(String namespace)
    Sets the namespace to use for the query. Query specified namespace takes precedence, else this namespace value is used for unqualified table names.
    Since:
      18.3

  - ### getNamespace

    public String getNamespace()
    Returns the namespace to use for the query, null if not set.
    Since:
      18.3

  - ### setMaxMemoryConsumption

    public void setMaxMemoryConsumption(long v)
    Set the maximum number of memory bytes that may be consumed by the statement at the client for blocking operations, such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting (sorting by distance when a query contains a geo_near() function). Such operations may consume a lot of memory as they need to cache the full result set at the client memory. The default value is 100MB.
    Since:
      18.3

  - ### getMaxMemoryConsumption

    public long getMaxMemoryConsumption()
    Get the maximum number of memory bytes that may be consumed by the statement at the client for blocking operations, such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting (sorting by distance when a query contains a geo_near() function). Such operations may consume a lot of memory as they need to cache the full result set at the client memory. The default value is 100MB.

  - ### setUpdateLimit

    public void setUpdateLimit(int limit)
    Sets the maximum number of records that can be updated in a single update query. The affected records in a update query are processed within a single transaction. If this limit is too large, it may impact other operations that need to read or write the data involved in the transaction. The default value is 1000.
    Since:
      25.1

  - ### getUpdateLimit

    public int getUpdateLimit()
    Returns the maximum number of records that can be updated in a single update query. The default value is 1000.
    Since:
      25.1

  - ### setQueryName

    public ExecuteOptions setQueryName(String n)

  - ### getQueryName

    public String getQueryName()