Package oracle.nosql.driver.ops

# Class QueryRequest

java.lang.Object
oracle.nosql.driver.ops.Request
oracle.nosql.driver.ops.DurableRequest
oracle.nosql.driver.ops.QueryRequest

All Implemented Interfaces:
  `AutoCloseable`

public class QueryRequest extends DurableRequest implements AutoCloseable
A request that represents a query. A query may be specified as either a textual SQL statement (a String) or a prepared query (an instance of `PreparedStatement`), which may include bind variables.

For performance reasons prepared queries are preferred for queries that may be reused. This is because prepared queries bypass query compilation. They also allow for parameterized queries using bind variables.

There are two ways to get the results of a query: using an iterator or loop through partial results.

Iterator

Use `NoSQLHandle.queryIterable(QueryRequest)` to get an iterable that contains all the results. Usage example:

        NoSQLHandle handle = ...;

        try (
            QueryRequest qreq = new QueryRequest().setStatement("select * from foo");
            QueryIterableResult qir = handle.queryIterable(qreq)) {
            for( MapValue row : qir) {
                // do something with row
            }
        }

Partial results

To compute and retrieve the full result set of a query, the same QueryRequest instance will, in general, have to be executed multiple times (via `NoSQLHandle.query(oracle.nosql.driver.ops.QueryRequest)`. Each execution returns a `QueryResult`, which contains a subset of the result set. The following code snipet illustrates a typical query execution:

     NoSQLHandle handle = ...;

     QueryRequest qreq = new QueryRequest().setStatement("select * from foo");

     do {
       QueryResult qres = handle.query(qreq);
       List<MapValue> results = qres.getResults();
       // do something with the results
     } while (!qreq.isDone())

Notice that a batch of results returned by a QueryRequest execution may be empty. This is because during each execution the query is allowed to read or write a maximum number of bytes. If this maximum is reached, execution stops. This can happen before any result was generated (for example, if none of the rows read satisfied the query conditions).

If an application wishes to terminate query execution before retrieving all the query results, it should call `close()` in order to release any local resources held by the query. This also allows the application to reuse the QueryRequest instance to run the same query from the beginning or a different query.

QueryRequest instances are not thread-safe. That is, if two or more application threads need to run the same query concurrently, they must create and use their own QueryRequest instances.

See Also:
  - `NoSQLHandle.queryIterable(QueryRequest)`
  - `NoSQLHandle.query(QueryRequest)`
  - `NoSQLHandle.prepare(PrepareRequest)`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `QueryRequest()`
  Default constructor for QueryRequest

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Terminates the query execution and releases any memory consumed by the query at the driver.
  `Consistency`
  `getConsistency()`
  Returns the consistency set for this request, or null if not set.
  `byte[]`
  `getContinuationKey()`
  Deprecated.
  `int`
  `getLimit()`
  Returns the limit on number of items returned by the operation.
  `MathContext`
  `getMathContext()`
  Returns the `MathContext` used for `BigDecimal` operations.
  `long`
  `getMaxMemoryConsumption()`
  Returns the maximum number of memory bytes that may be consumed by the statement at the driver for 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).
  `int`
  `getMaxReadKB()`
  Returns the limit on the total data read during this operation, in KB.
  `int`
  `getMaxWriteKB()`
  Returns the limit on the total data written during this operation, in KB.
  `PreparedStatement`
  `getPreparedStatement()`
  Returns the prepared query statement
  `String`
  `getStatement()`
  Returns the query statement
  `int`
  `getTimeout()`
  Returns the timeout to use for the operation, in milliseconds.
  `String`
  `getTypeName()`
  Returns the type name of the request.
  `boolean`
  `isDone()`
  Returns true if the query execution is finished, i.e., there are no more query results to be generated.
  `QueryRequest`
  `setCompartment(String compartment)`
  Cloud service only.
  `QueryRequest`
  `setConsistency(Consistency consistency)`
  Sets the `Consistency` to use for the operation
  `QueryRequest`
  `setContinuationKey(byte[] continuationKey)`
  Deprecated.
  There is no reason to use this method anymore, because setting the continuation key is now done internally.
  `QueryRequest`
  `setDurability(Durability durability)`
  Sets the durability to use for the operation.
  `QueryRequest`
  `setLimit(int limit)`
  Sets the limit on number of items returned by the operation.
  `QueryRequest`
  `setMathContext(MathContext mathContext)`
  Sets the `MathContext` used for `BigDecimal` operations.
  `QueryRequest`
  `setMaxMemoryConsumption(long maxBytes)`
  Sets the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting.
  `QueryRequest`
  `setMaxReadKB(int maxReadKB)`
  Sets the limit on the total data read during this operation, in KB.
  `QueryRequest`
  `setMaxWriteKB(int maxWriteKB)`
  Sets the limit on the total data written during this operation, in KB.
  `QueryRequest`
  `setNamespace(String namespace)`
  Sets the optional namespace.
  `QueryRequest`
  `setPreparedStatement(PreparedStatement preparedStatement)`
  Sets the prepared query statement.
  `QueryRequest`
  `setPreparedStatement(PrepareResult prepareResult)`
  A convenience method to set the prepared query statement from a PrepareResult
  `QueryRequest`
  `setStatement(String statement)`
  Sets the query statement.
  `QueryRequest`
  `setTimeout(int timeoutMs)`
  Sets the request timeout value, in milliseconds.

  ### Methods inherited from class oracle.nosql.driver.ops.DurableRequest

  `getDurability`

  ### Methods inherited from class oracle.nosql.driver.ops.Request

  `getCompartment, getNamespace, getRateLimitDelayedMs, getReadRateLimiter, getRetryStats, getWriteRateLimiter, setReadRateLimiter, setWriteRateLimiter`

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

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

- ## Constructor Details

  - ### QueryRequest

    public QueryRequest()
    Default constructor for QueryRequest

- ## Method Details

  - ### setCompartment

    public QueryRequest setCompartment(String compartment)
    Cloud service only.

    Sets the name or id of a compartment to be used for this operation.

    The compartment may be specified as either a name (or path for nested compartments) or as an id (OCID). A name (vs id) can only be used when authenticated using a specific user identity. It is not available if authenticated as an Instance Principal which can be done when calling the service from a compute instance in the Oracle Cloud Infrastructure. See `SignatureProvider.createWithInstancePrincipal()`

    Parameters:
      `compartment` - the name or id. If using a nested compartment, specify the full compartment path `compartmentA.compartmentB`, but exclude the name of the root compartment (tenant).
    Returns:
      this

  - ### getLimit

    public int getLimit()
    Returns the limit on number of items returned by the operation. If not set by the application this value will be 0 which means no limit set. For update query with on-premise service, returns the update limit on the number of records that can be updated in single update query. If not set by the application this value will be 0 which means no application limit set.
    Returns:
      the limit, or 0 if not set

  - ### setLimit

    public QueryRequest setLimit(int limit)
    Sets the limit on number of items returned by the operation. This allows an operation to return less than the default amount of data. For update query, if with on-premise service, this is to set the update limit on the number of records that can be updated in single query, if not set by the application, default service limit is used. If with cloud service, this update limit will be ignored, the maximum of records that can be updated is limited by other cloud limits maxWriteKB and maxReadKB.
    Parameters:
      `limit` - the limit in terms of number of items returned, or the maximum of records that can be updated in a update query.
    Returns:
      this
    Throws:
      `IllegalArgumentException` - if the limit value is less than 0.

  - ### getMaxReadKB

    public int getMaxReadKB()
    Returns the limit on the total data read during this operation, in KB. If not set by the application this value will be 0 which means no application-defined limit.
    Returns:
      the limit, or 0 if not set

  - ### setMaxReadKB

    public QueryRequest setMaxReadKB(int maxReadKB)
    Sets the limit on the total data read during this operation, in KB. This value can only reduce the system defined limit. This limit is independent of read units consumed by the operation. It is recommended that for tables with relatively low provisioned read throughput that this limit be reduced to less than or equal to one half of the provisioned throughput in order to avoid or reduce throttling exceptions.
    Parameters:
      `maxReadKB` - the limit in terms of number of KB read during this operation.
    Returns:
      this
    Throws:
      `IllegalArgumentException` - if the maxReadKB value is less than 0

  - ### getMaxWriteKB

    public int getMaxWriteKB()
    Returns the limit on the total data written during this operation, in KB. If not set by the application this value will be 0 which means no application-defined limit.
    Returns:
      the limit, or 0 if not set

  - ### setMaxWriteKB

    public QueryRequest setMaxWriteKB(int maxWriteKB)
    Sets the limit on the total data written during this operation, in KB. This limit is independent of write units consumed by the operation.
    Parameters:
      `maxWriteKB` - the limit in terms of number of KB written during this operation.
    Returns:
      this
    Throws:
      `IllegalArgumentException` - if the maxWriteKB value is less than 0

  - ### setMaxMemoryConsumption

    public QueryRequest setMaxMemoryConsumption(long maxBytes)
    Sets the maximum number of memory bytes that may be consumed by the statement at the driver for operations such as duplicate elimination (which may be required due to the use of an index on an array or map) and sorting. Such operations may consume a lot of memory as they need to cache the full result set or a large subset of it at the client memory. If the maximum amount of memory is exceeded, a exception will be throw.

    The default value is 1GB.

    Parameters:
      `maxBytes` - the amount of memory to use, in bytes
    Returns:
      this

  - ### getMaxMemoryConsumption

    public long getMaxMemoryConsumption()
    Returns the maximum number of memory bytes that may be consumed by the statement at the driver for 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 1GB.

    Returns:
      the maximum number of memory bytes

  - ### getMathContext

    public MathContext getMathContext()
    Returns the `MathContext` used for `BigDecimal` operations. `MathContext.DECIMAL32` is used by default.
    Returns:
      the MathContext to use for the query

  - ### setMathContext

    public QueryRequest setMathContext(MathContext mathContext)
    Sets the `MathContext` used for `BigDecimal` operations. `MathContext.DECIMAL32` is used by default.
    Parameters:
      `mathContext` - the MathContext to use for the query
    Returns:
      this

  - ### getStatement

    public String getStatement()
    Returns the query statement
    Returns:
      the statement, or null if it has not been set

  - ### setStatement

    public QueryRequest setStatement(String statement)
    Sets the query statement.
    Parameters:
      `statement` - the query statement
    Returns:
      this

  - ### getPreparedStatement

    public PreparedStatement getPreparedStatement()
    Returns the prepared query statement
    Returns:
      the statement, or null if it has not been set

  - ### setPreparedStatement

    public QueryRequest setPreparedStatement(PreparedStatement preparedStatement)
    Sets the prepared query statement.
    Parameters:
      `preparedStatement` - the prepared query statement
    Returns:
      this

  - ### setPreparedStatement

    public QueryRequest setPreparedStatement(PrepareResult prepareResult)
    A convenience method to set the prepared query statement from a PrepareResult
    Parameters:
      `prepareResult` - the result of a prepare request
    Returns:
      this

  - ### getContinuationKey

    @Deprecated public byte[] getContinuationKey()
    Deprecated.
    Returns the continuation key if set
    Returns:
      the key

  - ### setContinuationKey

    @Deprecated public QueryRequest setContinuationKey(byte[] continuationKey)
    Deprecated.
    There is no reason to use this method anymore, because setting the continuation key is now done internally.
    Sets the continuation key. This is used to continue an operation that returned this key in its `QueryResult`.
    Parameters:
      `continuationKey` - the key which should have been obtained from `QueryResult.getContinuationKey()`
    Returns:
      this;

  - ### isDone

    public boolean isDone()
    Returns true if the query execution is finished, i.e., there are no more query results to be generated. Otherwise false.
    Returns:
      whether the query is execution is finished or not

  - ### close

    public void close()
    Terminates the query execution and releases any memory consumed by the query at the driver. An application should use this method if it wishes to terminate query execution before retrieving all of the query results.
    Specified by:
      `close` in interface `AutoCloseable`

  - ### setConsistency

    public QueryRequest setConsistency(Consistency consistency)
    Sets the `Consistency` to use for the operation
    Parameters:
      `consistency` - the Consistency
    Returns:
      this

  - ### setDurability

    public QueryRequest setDurability(Durability durability)
    Sets the durability to use for the operation. On-premises only. This setting only applies if the query modifies a row using an INSERT, UPSERT, or DELETE statement. If the query is read-only it is ignored.
    Parameters:
      `durability` - the durability value. Set to null for the default durability setting on the server.
    Returns:
      this
    Since:
      5.4.0

  - ### getConsistency

    public Consistency getConsistency()
    Returns the consistency set for this request, or null if not set.
    Returns:
      the consistency

  - ### setTimeout

    public QueryRequest setTimeout(int timeoutMs)
    Sets the request timeout value, in milliseconds. This overrides any default value set with `NoSQLHandleConfig.setRequestTimeout(int)`. The value must be positive.
    Parameters:
      `timeoutMs` - the timeout value, in milliseconds
    Returns:
      this
    Throws:
      `IllegalArgumentException` - if the timeout value is less than or equal to 0

  - ### setNamespace

    public QueryRequest setNamespace(String namespace)
    Sets the optional namespace. On-premises only. This overrides any default value set with `NoSQLHandleConfig.setDefaultNamespace(java.lang.String)`. Note: if a namespace is specified in the table name in the SQL statement (using the namespace:tablename format), that value will override this setting.
    Parameters:
      `namespace` - the namespace to use for the operation
    Returns:
      this
    Since:
      5.4.10

  - ### getTimeout

    public int getTimeout()
    Returns the timeout to use for the operation, in milliseconds. A value of 0 indicates that the timeout has not been set.
    Returns:
      the value

  - ### getTypeName

    public String getTypeName()
    Description copied from class: `Request`
    Returns the type name of the request. This is used for stats.
    Specified by:
      `getTypeName` in class `Request`
    Returns:
      the type name of the request