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

#include <couchbase/search_options.hxx>

Inheritance diagram for search_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	client_context_id (std::string client_context_id) -> search_options &
	Supports providing a custom client context ID for this query.

auto	scan_consistency (search_scan_consistency scan_consistency) -> search_options &
	Customizes the consistency guarantees for this query.

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

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

auto	skip (std::uint32_t skip) -> search_options &
	Set the number of rows to skip (eg.

auto	limit (std::uint32_t limit) -> search_options &
	Add a limit to the query on the number of rows it can return.

auto	explain (bool explain) -> search_options &
	Activates or deactivates the explanation of each result hit in the response, according to the parameter.

auto	disable_scoring (bool disable) -> search_options &
	If set to true, thee server will not perform any scoring on the hits.

auto	include_locations (bool include) -> search_options &
	If set to true, will include the search_row::locations().

auto	collections (std::vector< std::string > collections) -> search_options &
	Allows to limit the search query to a specific list of collection names.

auto	fields (std::vector< std::string > fields) -> search_options &
	Configures the list of fields for which the whole value should be included in the response.

auto	highlight (highlight_style style=highlight_style::html, std::vector< std::string > fields={}) -> search_options &
	Configures the highlighting of matches in the response.

auto	highlight (std::vector< std::string > fields) -> search_options &
	Configures the highlighting of matches in the response for all fields, using the server's default highlighting style.

auto	sort (std::vector< std::string > sort_expressions) -> search_options &
	Configures the list of fields (including special fields) which are used for sorting purposes.

auto	sort (std::vector< std::shared_ptr< search_sort > > sort_objects) -> search_options &
	Configures the list of search_sort instances which are used for sorting purposes.

auto	facets (std::map< std::string, std::shared_ptr< search_facet > > facets) -> search_options &
	Sets list of search_facet to the query.

template<typename... Facets>
auto	facets (const Facets &... facets) -> search_options &
	Sets list of search_facet to the query.

auto	facet (std::string name, std::shared_ptr< search_facet > facet) -> search_options &
	Adds one search_facet to the query.

template<typename Facet >
auto	facet (std::string name, Facet facet) -> search_options &
	Adds one search_facet to the query.

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

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

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

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

Detailed Description

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

Since: 1.0.0

Committed: Generally available API and should be preferred in production

Member Function Documentation

◆ 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 ) -> search_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

◆ collections()

auto collections ( std::vector< std::string > collections ) -> search_options&

inline

Allows to limit the search query to a specific list of collection names.

Note: this is only supported with server 7.0 and later.

Parameters

collections

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 ) -> search_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(search_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.

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

◆ disable_scoring()

auto disable_scoring ( bool disable ) -> search_options&

inline

If set to true, thee server will not perform any scoring on the hits.

Parameters

disable

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ explain()

auto explain ( bool explain ) -> search_options&

inline

Activates or deactivates the explanation of each result hit in the response, according to the parameter.

Parameters

explain

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ facet() [1/2]

template<typename Facet >

auto facet	(	std::string	name,
		Facet	facet ) -> search_options&

inline

Adds one search_facet to the query.

This is an additive operation (the given facets are added to any facet previously requested), but if an existing facet has the same name it will be replaced.

This drives the inclusion of the facets in the search_result.

Note: to be faceted, a field's value must be stored in the FTS index.

Template Parameters

Facet type of the facet, that derived from the search_facet

Parameters

name
facet

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ facet() [2/2]

auto facet	(	std::string	name,
		std::shared_ptr< search_facet >	facet ) -> search_options&

inline

Adds one search_facet to the query.

This is an additive operation (the given facets are added to any facet previously requested), but if an existing facet has the same name it will be replaced.

This drives the inclusion of the facets in the search_result.

Note: to be faceted, a field's value must be stored in the FTS index.

Parameters

name
facet

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ facets() [1/2]

template<typename... Facets>

auto facets ( const Facets &... facets ) -> search_options&

inline

Sets list of search_facet to the query.

This drives the inclusion of the facets in the search_result.

Note: to be faceted, a field's value must be stored in the FTS index.

Parameters

facets pairs of std::string name and value derived from search_facet

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ facets() [2/2]

auto facets ( std::map< std::string, std::shared_ptr< search_facet > > facets ) -> search_options&

inline

Sets list of search_facet to the query.

This drives the inclusion of the facets in the search_result.

Note: to be faceted, a field's value must be stored in the FTS index.

Parameters

facets

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ fields()

auto fields ( std::vector< std::string > fields ) -> search_options&

inline

Configures the list of fields for which the whole value should be included in the response.

If empty, no field values are included.

This drives the inclusion of the fields in each search_row hit.

Note: to be highlighted, the fields must be stored in the FTS index.

Parameters

fields

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ highlight() [1/2]

auto highlight	(	highlight_style	style = highlight_style::html,
		std::vector< std::string >	fields = {} ) -> search_options&

inline

Configures the highlighting of matches in the response.

This drives the inclusion of the search_row::fragments() fragments in each search_row hit.

Note: to be highlighted, the fields must be stored in the FTS index.

Parameters

style
fields

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ highlight() [2/2]

auto highlight ( std::vector< std::string > fields ) -> search_options&

inline

Configures the highlighting of matches in the response for all fields, using the server's default highlighting style.

This drives the inclusion of the search_row::fragments() fragments in each search_row hit.

Note: to be highlighted, the fields must be stored in the FTS index.

Parameters

fields

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ include_locations()

auto include_locations ( bool include ) -> search_options&

inline

If set to true, will include the search_row::locations().

Parameters

include

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ limit()

auto limit ( std::uint32_t limit ) -> search_options&

inline

Add a limit to the query on the number of rows it can return.

Parameters

limit

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 , typename Serializer = codec::tao_json_serializer, std::enable_if_t< codec::is_serializer_v< Serializer >, bool > = true>

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

◆ scan_consistency()

auto scan_consistency ( search_scan_consistency scan_consistency ) -> search_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 search_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.

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&).

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

◆ skip()

auto skip ( std::uint32_t skip ) -> search_options&

inline

Set the number of rows to skip (eg.

for pagination).

Parameters

skip

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ sort() [1/2]

auto sort ( std::vector< std::shared_ptr< search_sort > > sort_objects ) -> search_options&

inline

Configures the list of search_sort instances which are used for sorting purposes.

If empty, the default sorting (descending by score) is used by the server.

If no sort is provided, it is equal to sort("-_score"), since the server will sort it by score in descending order.

Parameters

sort_objects

Returns: this options builder for chaining purposes.

Since: 1.0.0

Committed: Generally available API and should be preferred in production

◆ sort() [2/2]

auto sort ( std::vector< std::string > sort_expressions ) -> search_options&

inline

Configures the list of fields (including special fields) which are used for sorting purposes.

If empty, the default sorting (descending by score) is used by the server.

The list of sort fields can include actual fields (like "firstname" but then they must be stored in the index, configured in the server side mapping). Fields provided first are considered first and in a "tie" case the next sort field is considered. So sorting by "firstname" and then "lastname" will first sort ascending by the firstname and if the names are equal then sort ascending by lastname. Special fields like "_id" and "_score" can also be used. If prefixed with "-" the sort order is set to descending.

If no sort is provided, it is equal to sort("-_score"), since the server will sort it by score in descending order.

Parameters

sort_expressions

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/search_options.hxx

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ build()

◆ client_context_id()

◆ collections()

◆ consistent_with()

◆ disable_scoring()

◆ explain()

◆ facet() [1/2]

◆ facet() [2/2]

◆ facets() [1/2]

◆ facets() [2/2]

◆ fields()

◆ highlight() [1/2]

◆ highlight() [2/2]

◆ include_locations()

◆ limit()

◆ raw()

◆ scan_consistency()

◆ skip()

◆ sort() [1/2]

◆ sort() [2/2]