Class QueryRequest
- All Implemented Interfaces:
AutoCloseable
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 snippet
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.
Parallel queries
By default a query request operates over all of the rows in a table. Large scale analytics, such as Apache Spark, Apache Hadoop, and others benefit from the ability to split a query into multiple workloads, where each workload operates on a distinct subset of a table's rows. This feature is called "parallel query" and is enabled in this driver as of release 5.4.18. The feature also requires a server that supports the feature. A server that does not support the feature will always return 0 for the maximum amount of parallelism mentioned below.
Parallel query allows an application to create a group of participating
queries that operate in their own threads, processes, or machines. Each
participant query declares itself to be N of M cooperating queries, where
N is the individual operation and M is the total number of cooperating
queries. The maximum value for M is returned in the
PreparedStatement
returned in a PrepareResult
. This
feature works best for queries that operate over the entire set of data or
a simple subset constrained by a predicate. Parallel queries cannot be
performed on aggregations and sorted queries. Sample code to use this
feature looks like this
NoSQLHandle handle = ...; PreparedStatement ps = handle.prepare(new PrepareRequest().setStatement( "select * from foo")).getPreparedStatement(); int maxParallelism = ps.getMaximumParallelism(); // at this point up to maxParallelism queries can be operated independently, // each one operating on a subset of data. The total number of cooperating // queries can be up to maxParallelism, but smaller numbers are fine. The // system decides how to partition the queries across unique rows // Consider a maxParallism of 100 and 10 cooperating threads or processes // are desired. This is an example of what number 3 out of 10 would do to // execute a cooperating query QueryRequest qreq = new QueryRequest().setPreparedStatement(ps). setNumberOfOperations(10) // total number of ops cooperating setOperationNumber(3) // this is number 3 of 10The query would then be executed as normal but instead of operating over the entire table the query will operate only on approximately 1/10 of the data. It is up to the application to aggregate and process results from cooperating queries. If they are to be run in separate threads or processes it is up to the application to create those runtime entities as well.
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.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Terminates the query execution and releases any memory consumed by the query at the driver.Returns the consistency set for this request, or null if not set.byte[]
Deprecated.int
getLimit()
Returns the limit on number of items returned by the operation.Returns theMathContext
used forBigDecimal
operations.long
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
Returns the limit on the total data read during this operation, in KB.int
Returns the limit on the total data written during this operation, in KB.int
Returns the total number of operations in a coordinated parallel query operation or 0 if this is not a parallel query.int
Returns the individual operation number for this query if it is participating in a coordinated parallel query operation or 0 if not.Returns the prepared query statementThis method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.Returns the query statementint
Returns the timeout to use for the operation, in milliseconds.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.setCompartment
(String compartment) Cloud service only.setConsistency
(Consistency consistency) Sets theConsistency
to use for the operationsetContinuationKey
(byte[] continuationKey) Deprecated.There is no reason to use this method anymore, because setting the continuation key is now done internally.setDurability
(Durability durability) Sets the durability to use for the operation.setLimit
(int limit) Sets the limit on number of items returned by the operation.setMathContext
(MathContext mathContext) Sets theMathContext
used forBigDecimal
operations.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.setMaxReadKB
(int maxReadKB) Sets the limit on the total data read during this operation, in KB.setMaxWriteKB
(int maxWriteKB) Sets the limit on the total data written during this operation, in KB.setNamespace
(String namespace) Sets the optional namespace.setNumberOfOperations
(int numberOfOperations) Sets the total number of operations in a coordinated parallel query operation.setOperationNumber
(int operationNumber) Sets the individual operation number for this query if it is participating in a coordinated parallel query operation.setPreparedStatement
(PreparedStatement preparedStatement) Sets the prepared query statement.setPreparedStatement
(PrepareResult prepareResult) A convenience method to set the prepared query statement from a PrepareResultsetRowMetadata
(String rowMetadata) This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.setStatement
(String statement) Sets the query statement.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
-
Constructor Details
-
QueryRequest
public QueryRequest()Default constructor for QueryRequest
-
-
Method Details
-
setCompartment
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 pathcompartmentA.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
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
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
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
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
- Returns:
- the MathContext to use for the query
-
setMathContext
- Parameters:
mathContext
- the MathContext to use for the query- Returns:
- this
-
getStatement
Returns the query statement- Returns:
- the statement, or null if it has not been set
-
setStatement
Sets the query statement.- Parameters:
statement
- the query statement- Returns:
- this
-
getPreparedStatement
Returns the prepared query statement- Returns:
- the statement, or null if it has not been set
-
setPreparedStatement
Sets the prepared query statement.- Parameters:
preparedStatement
- the prepared query statement- Returns:
- this
-
setPreparedStatement
A convenience method to set the prepared query statement from a PrepareResult- Parameters:
prepareResult
- the result of a prepare request- Returns:
- this
-
getContinuationKey
Deprecated.Returns the continuation key if set- Returns:
- the key
-
setContinuationKey
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 itsQueryResult
.- Parameters:
continuationKey
- the key which should have been obtained fromQueryResult.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 interfaceAutoCloseable
-
setConsistency
Sets theConsistency
to use for the operation- Parameters:
consistency
- the Consistency- Returns:
- this
-
setDurability
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
Returns the consistency set for this request, or null if not set.- Returns:
- the consistency
-
setRowMetadata
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 is optional and only applies if the query modifies or deletes any rows using an INSERT, UPDATE, UPSERT or DELETE statement. If the query is read-only this setting 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 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 construct- Since:
- 5.4.18
-
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 set for this request, or null if not set.
- Returns:
- the row metadata
- Since:
- 5.4.18
-
setTimeout
Sets the request timeout value, in milliseconds. This overrides any default value set withNoSQLHandleConfig.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
Sets the optional namespace. On-premises only. This overrides any default value set withNoSQLHandleConfig.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
-
getNumberOfOperations
public int getNumberOfOperations()Returns the total number of operations in a coordinated parallel query operation or 0 if this is not a parallel query.- Returns:
- the number of operations
- Since:
- 5.4.18
-
getOperationNumber
public int getOperationNumber()Returns the individual operation number for this query if it is participating in a coordinated parallel query operation or 0 if not. The value is 1-based.- Returns:
- the operation number
- Since:
- 5.4.18
-
setNumberOfOperations
Sets the total number of operations in a coordinated parallel query operation. This value will only be valid if the request contains a prepared query and must be less than or equal to the value returned byPreparedStatement.getMaximumParallelism()
. Validation is performed during query execution.- Parameters:
numberOfOperations
- the number of operations- Returns:
- this
- Since:
- 5.4.18
-
setOperationNumber
Sets the individual operation number for this query if it is participating in a coordinated parallel query operation. This number must be less than or equal to the total number of operations. The operation number is 1-based and the value will only be valid if the request contains a prepared query. Validation is performed during query execution.- Parameters:
operationNumber
- the operation number- Returns:
- this
- Since:
- 5.4.18
-
getTypeName
Description copied from class:Request
Returns the type name of the request. This is used for stats.- Specified by:
getTypeName
in classRequest
- Returns:
- the type name of the request
-