Class QueryOptions
- java.lang.Object
-
- com.couchbase.client.java.CommonOptions<QueryOptions>
-
- com.couchbase.client.java.query.QueryOptions
-
public class QueryOptions extends CommonOptions<QueryOptions>
Allows customizing various N1QL query options.This object is NOT thread safe and must be constructed on a single thread and then passed to the
Cluster.query(String, QueryOptions)method.- Since:
- 3.0.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description classQueryOptions.Built-
Nested classes/interfaces inherited from class com.couchbase.client.java.CommonOptions
CommonOptions.BuiltCommonOptions
-
-
Constructor Summary
Constructors Modifier Constructor Description protectedQueryOptions()The options should only be instantiated through thequeryOptions()static method.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description QueryOptionsadhoc(boolean adhoc)Allows turning this request into a prepared statement query.QueryOptionsasTransaction()Performs this as a single query transaction, with default options.QueryOptionsasTransaction(SingleQueryTransactionOptions options)Performs this as a single query transaction.QueryOptions.Builtbuild()QueryOptionsclientContextId(String clientContextId)Supports providing a custom client context ID for this query.QueryOptionsconsistentWith(MutationState mutationState)Sets theMutationTokens this query should be consistent with.QueryOptionsflexIndex(boolean flexIndex)Tells the query engine to use a flex index (utilizing the search service).QueryOptionsmaxParallelism(int maxParallelism)Allows overriding the default maximum parallelism for the query execution on the server side.QueryOptionsmetrics(boolean metrics)Enables per-request metrics in the trailing section of the query.QueryOptionsparameters(JsonArray positional)Sets positional parameters for this query.QueryOptionsparameters(JsonObject named)Sets named parameters for this query.QueryOptionspipelineBatch(int pipelineBatch)Supports customizing the number of items execution operators can batch for fetch from the KV layer on the server.QueryOptionspipelineCap(int pipelineCap)Allows customizing the maximum number of items each execution operator can buffer between various operators on the server.QueryOptionspreserveExpiry(boolean preserveExpiry)Tells the query engine to preserve expiration values set on any documents modified by this query.QueryOptionsprofile(QueryProfile profile)Customizes the server profiling level for this query.static QueryOptionsqueryOptions()Creates newQueryOptionswith all default params set.QueryOptionsraw(String key, Object value)Allows providing custom JSON key/value pairs for advanced usage.QueryOptionsreadonly(boolean readonly)Allows explicitly marking a query as being readonly and not mutating and documents on the server side.QueryOptionsscanCap(int scanCap)Supports customizing the maximum buffered channel size between the indexer and the query service.QueryOptionsscanConsistency(QueryScanConsistency scanConsistency)Customizes the consistency guarantees for this query.QueryOptionsscanWait(Duration wait)Allows customizing how long the query engine is willing to wait until the index catches up to whatever scan consistency is asked for in this query.QueryOptionsserializer(JsonSerializer serializer)Provides a customJsonSerializerto be used for decoding the rows as they return from the server.-
Methods inherited from class com.couchbase.client.java.CommonOptions
clientContext, parentSpan, retryStrategy, self, timeout
-
-
-
-
Constructor Detail
-
QueryOptions
protected QueryOptions()
The options should only be instantiated through thequeryOptions()static method.
-
-
Method Detail
-
queryOptions
public static QueryOptions queryOptions()
Creates newQueryOptionswith all default params set.- Returns:
- constructed
QueryOptionswith its default values.
-
raw
public QueryOptions raw(String key, Object value)
Allows providing custom JSON key/value pairs for advanced usage.If available, it is recommended to use the methods on this object to customize the query. This method should only be used if no such setter can be found (i.e. if an undocumented property should be set or you are using an older client and a new server-configuration property has been added to the cluster).
Note that the value will be passed through a JSON encoder, so do not provide already encoded JSON as the value. If you want to pass objects or arrays, you can use
JsonObjectandJsonArrayrespectively.- Parameters:
key- the parameter name (key of the JSON property) or empty.value- the parameter value (value of the JSON property).- Returns:
- the same
QueryOptionsfor chaining purposes.
-
adhoc
public QueryOptions adhoc(boolean adhoc)
Allows turning this request into a prepared statement query.If set to
false
, the SDK will transparently perform "prepare and execute" logic the first time this query is seen and then subsequently reuse the prepared statement name when sending it to the server. If a query is executed frequently, this is a good way to speed it up since it will save the server the task of re-parsing and analyzing the query.If you are using prepared statements, make sure that if certain parts of the query string change you are using
namedorpositionalparameters. If the statement string itself changes it cannot be cached.- Parameters:
adhoc- if set to false this query will be turned into a prepared statement query.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
scanConsistency
public QueryOptions scanConsistency(QueryScanConsistency scanConsistency)
Customizes the consistency guarantees for this query.Tuning the scan consistency allows to trade data "freshness" for latency and vice versa. By default
QueryScanConsistency.NOT_BOUNDEDis used, which means that the server returns the data it has in the index right away. This is fast, but might not include the most recent mutations. If you want to include all the mutations up to the point of the query, useQueryScanConsistency.REQUEST_PLUS.Note that you cannot use this method and
consistentWith(MutationState)at the same time, since they are mutually exclusive. As a rule of thumb, if you only care to be consistent with the mutation you just wrote on the same thread/app, useconsistentWith(MutationState). If you need "global" scan consistency, useQueryScanConsistency.REQUEST_PLUSon this method.- Parameters:
scanConsistency- the index scan consistency to be used for this query.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
serializer
public QueryOptions serializer(JsonSerializer serializer)
Provides a customJsonSerializerto be used for decoding the rows as they return from the server.If no serializer is provided, the default one from the
ClusterEnvironmentwill be used (which is sufficient for most tasks at hand).- Parameters:
serializer- a custom serializer for this request.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
profile
public QueryOptions profile(QueryProfile profile)
Customizes the server profiling level for this query.Note that you only want to tune this if you want to gather profiling/performance metrics for debugging. Turning this on in production (depending on the level) will likely have performance impact on the server query engine as a whole and on this query in particular!
This is an Enterprise Edition feature. On Community Edition the parameter will be accepted, but no profiling information returned.
- Parameters:
profile- the custom query profile level for this query.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
clientContextId
public QueryOptions clientContextId(String clientContextId)
Supports providing a custom client context ID for this query.If no client context ID is provided by the user, a UUID is generated and sent automatically so by default it is always possible to identify a query when debugging. If you do not want to send one, pass either null or an empty string to this method.
- Parameters:
clientContextId- the client context ID - if null or empty it will not be sent.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
metrics
public QueryOptions metrics(boolean metrics)
Enables per-request metrics in the trailing section of the query.If this method is set to true, the server will send metrics back to the client which are available through the
QueryMetaData.metrics()section. As opposed toprofile(QueryProfile), returning metrics is rather cheap and can also be enabled in production if needed.- Parameters:
metrics- set to true if the server should return simple query metrics.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
scanWait
public QueryOptions scanWait(Duration wait)
Allows customizing how long the query engine is willing to wait until the index catches up to whatever scan consistency is asked for in this query.Note that if
QueryScanConsistency.NOT_BOUNDEDis used, this method doesn't do anything at all. If no value is provided to this method, the server default is used.- Parameters:
wait- the maximum duration the query engine is willing to wait before failing.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
maxParallelism
public QueryOptions maxParallelism(int maxParallelism)
Allows overriding the default maximum parallelism for the query execution on the server side.If 0 or a negative value is set, the parallelism is disabled. If not provided, the server default will be used.
- Parameters:
maxParallelism- the maximum parallelism for this query, 0 or negative values disable it.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
readonly
public QueryOptions readonly(boolean readonly)
Allows explicitly marking a query as being readonly and not mutating and documents on the server side.In addition to providing some security in that you are not accidentally modifying data, setting this flag to true also helps the client to more proactively retry and re-dispatch a query since then it can be sure it is idempotent. As a result, if your query is readonly then it is a good idea to set this flag.
If set to true, then (at least) the following statements are not allowed:
- CREATE INDEX
- DROP INDEX
- INSERT
- MERGE
- UPDATE
- UPSERT
- DELETE
- Parameters:
readonly- true if readonly should be set, false is the default and will use the server side default.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
scanCap
public QueryOptions scanCap(int scanCap)
Supports customizing the maximum buffered channel size between the indexer and the query service.This is an advanced API and should only be tuned with care. Use 0 or a negative number to disable.
- Parameters:
scanCap- the scan cap size, use 0 or negative number to disable.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
pipelineBatch
public QueryOptions pipelineBatch(int pipelineBatch)
Supports customizing the number of items execution operators can batch for fetch from the KV layer on the server.This is an advanced API and should only be tuned with care.
- Parameters:
pipelineBatch- the pipeline batch size.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
pipelineCap
public QueryOptions pipelineCap(int pipelineCap)
Allows customizing the maximum number of items each execution operator can buffer between various operators on the server.This is an advanced API and should only be tuned with care.
- Parameters:
pipelineCap- the pipeline cap size.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
parameters
public QueryOptions parameters(JsonObject named)
Sets named parameters for this query.Note that named and positional parameters cannot be used at the same time. If one is set, the other one is "nulled" out and not being sent to the server.
- Parameters:
named-JsonObjectthe named parameters.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
parameters
public QueryOptions parameters(JsonArray positional)
Sets positional parameters for this query.Note that named and positional parameters cannot be used at the same time. If one is set, the other one is "nulled" out and not being sent to the server.
- Parameters:
positional-JsonArraythe positional parameters.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
consistentWith
public QueryOptions consistentWith(MutationState mutationState)
Sets theMutationTokens this query should be consistent with.These mutation tokens are returned from mutations (i.e. as part of a
MutationResult) and if you want your N1QL query to include those you need to pass the mutation tokens into aMutationState.Note that you cannot use this method and
scanConsistency(QueryScanConsistency)at the same time, since they are mutually exclusive. As a rule of thumb, if you only care to be consistent with the mutation you just wrote on the same thread/app, use this method. If you need "global" scan consistency, useQueryScanConsistency.REQUEST_PLUSonscanConsistency(QueryScanConsistency).- Parameters:
mutationState- the mutation state containing the mutation tokens.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
flexIndex
public QueryOptions flexIndex(boolean flexIndex)
Tells the query engine to use a flex index (utilizing the search service).- Parameters:
flexIndex- if a flex index should be used, false is the default.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
preserveExpiry
@SinceCouchbase("7.1") public QueryOptions preserveExpiry(boolean preserveExpiry)
Tells the query engine to preserve expiration values set on any documents modified by this query.This feature works from Couchbase Server 7.1.0 onwards.
- Parameters:
preserveExpiry- if expiration values should be preserved, the default is false.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
build
@Internal public QueryOptions.Built build()
-
asTransaction
@SinceCouchbase("7.0") public QueryOptions asTransaction()
Performs this as a single query transaction, with default options.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
asTransaction
@SinceCouchbase("7.0") public QueryOptions asTransaction(SingleQueryTransactionOptions options)
Performs this as a single query transaction.- Parameters:
options- configuration options to use.- Returns:
- the same
QueryOptionsfor chaining purposes.
-
-