analytics_options Struct Reference

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

#include <couchbase/analytics_options.hxx>

Inheritance diagram for analytics_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	priority (bool prioritized) -> analytics_options &
	Allows to give certain requests higher priority than others.
auto	readonly (bool readonly) -> analytics_options &
	Allows explicitly marking a query as being readonly and not mutating and documents on the server side.
auto	scan_wait (std::chrono::milliseconds wait) -> analytics_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	client_context_id (std::string client_context_id) -> analytics_options &
	Supports providing a custom client context ID for this query.
auto	scan_consistency (analytics_scan_consistency scan_consistency) -> analytics_options &
	Customizes the consistency guarantees for this query.
auto	consistent_with (const mutation_state &state) -> analytics_options &
	Sets the mutation_tokens this query should be consistent with.
template<typename Value >
auto	raw (std::string name, const Value &value) -> analytics_options &
template<typename... Parameters>
auto	positional_parameters (const Parameters &... parameters) -> analytics_options &
	Set list of positional parameters for a query.
template<typename... Parameters>
auto	named_parameters (const Parameters &... parameters) -> analytics_options &
	Set list of named parameters for a query.
auto	encoded_raw_options (std::map< std::string, codec::binary, std::less<> > options) -> analytics_options &
	Set map of raw options for a query.
auto	encoded_positional_parameters (std::vector< codec::binary > parameters) -> analytics_options &
	Set list of positional parameters for a query.
auto	encoded_named_parameters (std::map< std::string, codec::binary, std::less<> > parameters) -> analytics_options &
	Set map of named parameters for a query.
Public Member Functions inherited from common_options< analytics_options >
auto	timeout (const std::chrono::milliseconds timeout) -> analytics_options &
	Specifies a custom per-operation timeout.
auto	retry_strategy (const std::shared_ptr< retry_strategy > strategy) -> analytics_options &
	Specifies a custom couchbase::retry_strategy for this operation.

Additional Inherited Members
Protected Member Functions inherited from common_options< analytics_options >
auto	build_common_options () const -> built
auto	self () -> analytics_options &
	Allows to return the right options builder instance for child implementations.

Detailed Description

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

Since

1.0.0

Committed

Generally available API and should be preferred in production

Member Function Documentation

build()

auto build ( ) const -> built

inline

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 ) -> analytics_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 ) -> analytics_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(analytics_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 analytics_scan_consistency#request_plus on scan_consistency(analytics_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 ) -> analytics_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 ) -> analytics_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 ) -> analytics_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

named_parameters()

template<typename... Parameters>

auto named_parameters ( const Parameters &... parameters ) -> analytics_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

positional_parameters()

template<typename... Parameters>

auto positional_parameters ( const Parameters &... parameters ) -> analytics_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

priority()

auto priority ( bool prioritized ) -> analytics_options&

inline

Allows to give certain requests higher priority than others.

Parameters

prioritized

if set to true this query will be treated with a higher priority by the service.

Returns

this options builder for chaining purposes.

Since

1.0.0

Committed

Generally available API and should be preferred in production

raw()

template<typename Value >

auto raw ( std::string name, const Value & value ) -> analytics_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 ) -> analytics_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.

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_consistency()

auto scan_consistency ( analytics_scan_consistency scan_consistency ) -> analytics_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 analytics_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 analytics_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 analytics_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 ) -> analytics_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 analytics_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

---

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

• couchbase/analytics_options.hxx