Options for cluster::query() and scope::query(). More...

#include <couchbase/query_options.hxx>

Inheritance diagram for query_options:

Classes
struct	built
	Immutable value object representing consistent options. More...

Public Member Functions
auto	build () const -> built
	Validates options and returns them as an immutable value.

auto	adhoc (bool adhoc) -> query_options &
	Allows turning this request into a prepared statement query.

auto	metrics (bool metrics) -> query_options &
	Enables per-request metrics in the trailing section of the query.

auto	profile (query_profile profile) -> query_options &
	Customizes the server profiling level for this query.

auto	readonly (bool readonly) -> query_options &
	Allows explicitly marking a query as being readonly and not mutating and documents on the server side.

auto	flex_index (bool flex_index) -> query_options &
	Tells the query engine to use a flex index (utilizing the search service).

auto	preserve_expiry (bool preserve_expiry) -> query_options &
	Tells the query engine to preserve expiration values set on any documents modified by this query.

auto	use_replica (bool use_replica) -> query_options &
	Specifies that the query engine should use replica nodes for KV fetches if the active node is down.

auto	max_parallelism (std::uint64_t max_parallelism) -> query_options &
	Allows overriding the default maximum parallelism for the query execution on the server side.

auto	scan_cap (std::uint64_t scan_cap) -> query_options &
	Supports customizing the maximum buffered channel size between the indexer and the query service.

auto	scan_wait (std::chrono::milliseconds wait) -> query_options &
	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.

auto	pipeline_batch (std::uint64_t pipeline_batch) -> query_options &
	Supports customizing the number of items execution operators can batch for fetch from the KV layer on the server.

auto	pipeline_cap (std::uint64_t pipeline_cap) -> query_options &
	Allows customizing the maximum number of items each execution operator can buffer between various operators on the server.

auto	client_context_id (std::string client_context_id) -> query_options &
	Supports providing a custom client context ID for this query.

auto	scan_consistency (query_scan_consistency scan_consistency) -> query_options &
	Customizes the consistency guarantees for this query.

auto	consistent_with (const mutation_state &state) -> query_options &
	Sets the `mutation_token`s this query should be consistent with.

template<typename Serializer = codec::tao_json_serializer, typename Value , std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>
auto	raw (std::string name, const Value &value) -> query_options &

template<typename Serializer = codec::tao_json_serializer, typename... Parameters, std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>
auto	positional_parameters (const Parameters &... parameters) -> query_options &
	Set list of positional parameters for a query.

template<typename Serializer = codec::tao_json_serializer, typename... Parameters, std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>
auto	named_parameters (const Parameters &... parameters) -> query_options &
	Set list of named parameters for a query.

auto	encoded_raw_options (std::map< std::string, codec::binary, std::less<> > options) -> query_options &
	Set map of raw options for a query.

auto	encoded_positional_parameters (std::vector< codec::binary > parameters) -> query_options &
	Set list of positional parameters for a query.

auto	encoded_named_parameters (std::map< std::string, codec::binary, std::less<> > parameters) -> query_options &
	Set map of named parameters for a query.

Public Member Functions inherited from common_options< query_options >
auto	timeout (const std::chrono::milliseconds timeout) -> query_options &
	Specifies a custom per-operation timeout.

auto	retry_strategy (const std::shared_ptr< retry_strategy > strategy) -> query_options &
	Specifies a custom `couchbase::retry_strategy` for this operation.

Additional Inherited Members
Protected Member Functions inherited from common_options< query_options >
auto	build_common_options () const -> built

auto	self () -> query_options &
	Allows to return the right options builder instance for child implementations.

Detailed Description

Options for cluster::query() and scope::query().

Since: 1.0.0

Committed: Generally available API and should be preferred in production

Member Function Documentation

◆ adhoc()

auto adhoc ( bool adhoc ) -> query_options&

inline

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 named_parameters() or positional_parameters(). 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: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ build()

auto build ( ) const -> built

inlinenodiscard

Validates options and returns them as an immutable value.

Returns: consistent options as an immutable value

Exceptions

std::system_error with code errc::common::invalid_argument if the options are not valid

Since: 1.0.0

Internal: Internal interface

◆ client_context_id()

auto client_context_id ( std::string client_context_id ) -> query_options&

inline

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.

Parameters

client_context_id the client context ID

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ consistent_with()

auto consistent_with ( const mutation_state & state ) -> query_options&

inline

Sets the mutation_tokens this query should be consistent with.

These mutation tokens are returned from mutations (i.e. as part of a mutation_result) and if you want your N1QL query to include those you need to pass the mutation tokens into a mutation_state.

Note that you cannot use this method and scan_consistency(query_scan_consistency) 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, use query_scan_consistency#request_plus on scan_consistency(query_scan_consistency).

Parameters

state the mutation state containing the mutation tokens.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ encoded_named_parameters()

auto encoded_named_parameters ( std::map< std::string, codec::binary, std::less<> > parameters ) -> query_options&

inline

Set map of named parameters for a query.

This function expects that all parameters encoded into pairs containing mapping names of the parameter to valid JSON values encoded as string.

Note: This function is low-level, and instead named_parameters() should be considered.

Parameters

parameters mapping of pairs, where each entry contains string with valid JSON value.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Uncommitted: Might be changed in the future, and eventually promoted to committed

◆ encoded_positional_parameters()

auto encoded_positional_parameters ( std::vector< codec::binary > parameters ) -> query_options&

inline

Set list of positional parameters for a query.

This function expects that all parameters encoded into byte strings containing valid JSON values.

Note: This function is low-level, and instead positional_parameters() should be considered.

Parameters

parameters vector of binaries, where each entry contains string with valid JSON value.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Uncommitted: Might be changed in the future, and eventually promoted to committed

◆ encoded_raw_options()

auto encoded_raw_options ( std::map< std::string, codec::binary, std::less<> > options ) -> query_options&

inline

Set map of raw options for a query.

This function expects that all parameters encoded into pairs containing mapping names of the parameter to valid JSON values encoded as string.

Note: This function is low-level, and instead raw() should be considered.

Parameters

options mapping of pairs, where each entry contains string with valid JSON value.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Uncommitted: Might be changed in the future, and eventually promoted to committed

◆ flex_index()

auto flex_index ( bool flex_index ) -> query_options&

inline

Tells the query engine to use a flex index (utilizing the search service).

Parameters

flex_index if a flex index should be used, false is the default.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ max_parallelism()

auto max_parallelism ( std::uint64_t max_parallelism ) -> query_options&

inline

Allows overriding the default maximum parallelism for the query execution on the server side.

If 0 value is set, the parallelism is disabled. If not provided, the server default will be used.

Parameters

max_parallelism the maximum parallelism for this query, 0 value disable it.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ metrics()

auto metrics ( bool metrics ) -> query_options&

inline

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 query_meta_data#metrics() section. As opposed to profile(query_profile), 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: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ named_parameters()

template<typename Serializer = codec::tao_json_serializer, typename... Parameters, std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>

auto named_parameters ( const Parameters &... parameters ) -> query_options&

inline

Set list of named parameters for a query.

Template Parameters

Parameters types for the parameter pairs

Parameters

parameters the sequence of name-value pairs. Each value will be encoded into JSON.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ pipeline_batch()

auto pipeline_batch ( std::uint64_t pipeline_batch ) -> query_options&

inline

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

pipeline_batch the pipeline batch size.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ pipeline_cap()

auto pipeline_cap ( std::uint64_t pipeline_cap ) -> query_options&

inline

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

pipeline_cap the pipeline cap size.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ positional_parameters()

template<typename Serializer = codec::tao_json_serializer, typename... Parameters, std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>

auto positional_parameters ( const Parameters &... parameters ) -> query_options&

inline

Set list of positional parameters for a query.

Template Parameters

Parameters types for the parameters

Parameters

parameters the sequence of positional parameters. Each entry will be encoded into JSON.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ preserve_expiry()

auto preserve_expiry ( bool preserve_expiry ) -> query_options&

inline

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

preserve_expiry whether expiration values should be preserved, the default is false.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ profile()

auto profile ( query_profile profile ) -> query_options&

inline

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: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ raw()

template<typename Serializer = codec::tao_json_serializer, typename Value , std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>

auto raw	(	std::string	name,
		const Value &	value ) -> query_options&

inline

Template Parameters

Value

Parameters

name
value

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ readonly()

auto readonly ( bool readonly ) -> query_options&

inline

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: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ scan_cap()

auto scan_cap ( std::uint64_t scan_cap ) -> query_options&

inline

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 to disable.

Parameters

scan_cap the scan cap size, use 0 value to disable.

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ scan_consistency()

auto scan_consistency ( query_scan_consistency scan_consistency ) -> query_options&

inline

Customizes the consistency guarantees for this query.

Tuning the scan consistency allows to trade data "freshness" for latency and vice versa. By default query_scan_consistency::not_bounded is 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, use query_scan_consistency::request_plus.

Note that you cannot use this method and consistent_with(const mutation_state&) 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 consistent_with(const mutation_state&). If you need "global" scan consistency, use query_scan_consistency::request_plus on this method.

Parameters

scan_consistency the index scan consistency to be used for this query

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ scan_wait()

auto scan_wait ( std::chrono::milliseconds wait ) -> query_options&

inline

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 query_scan_consistency::not_bounded is 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: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ use_replica()

auto use_replica ( bool use_replica ) -> query_options&

inline

Specifies that the query engine should use replica nodes for KV fetches if the active node is down.

Parameters

use_replica whether replica nodes should be used if the active node is down. If not provided, the server default will be used.

Returns: the options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

The documentation for this struct was generated from the following file:

couchbase/query_options.hxx

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ adhoc()

◆ build()

◆ client_context_id()

◆ consistent_with()

◆ encoded_named_parameters()

◆ encoded_positional_parameters()

◆ encoded_raw_options()

◆ flex_index()

◆ max_parallelism()

◆ metrics()

◆ named_parameters()

◆ pipeline_batch()

◆ pipeline_cap()

◆ positional_parameters()

◆ preserve_expiry()

◆ profile()

◆ raw()

◆ readonly()

◆ scan_cap()

◆ scan_consistency()

◆ scan_wait()

◆ use_replica()