collection Class Reference

The collection provides access to all collection APIs. More...

#include <couchbase/collection.hxx>

Public Member Functions
auto	bucket_name () const -> const std::string &
	Returns name of the bucket where the collection is defined.
auto	scope_name () const -> const std::string &
	Returns name of the scope where the collection is defined.
auto	name () const -> const std::string &
	Returns name of the collection.
auto	binary () const -> binary_collection
	Provides access to the binary APIs, not used for JSON documents.
void	get (std::string document_id, const get_options &options, get_handler &&handler) const
	Fetches the full document from this collection.
auto	get (std::string document_id, const get_options &options={}) const -> std::future< std::pair< error, get_result > >
	Fetches the full document from this collection.
void	get_and_touch (std::string document_id, std::chrono::seconds duration, const get_and_touch_options &options, get_and_touch_handler &&handler) const
	Fetches a full document and resets its expiration time to the value provided.
auto	get_and_touch (std::string document_id, std::chrono::seconds duration, const get_and_touch_options &options={}) const -> std::future< std::pair< error, get_result > >
	Fetches a full document and resets its expiration time to the value provided.
void	get_and_touch (std::string document_id, std::chrono::system_clock::time_point time_point, const get_and_touch_options &options, get_and_touch_handler &&handler) const
	Fetches a full document and resets its expiration time to the absolute value provided.
auto	get_and_touch (std::string document_id, std::chrono::system_clock::time_point time_point, const get_and_touch_options &options={}) const -> std::future< std::pair< error, get_result > >
	Fetches a full document and resets its expiration time to the absolute value provided.
void	touch (std::string document_id, std::chrono::seconds duration, const touch_options &options, touch_handler &&handler) const
	Updates the expiration a document given an id, without modifying or returning its value.
auto	touch (std::string document_id, std::chrono::seconds duration, const touch_options &options={}) const -> std::future< std::pair< error, result > >
	Updates the expiration a document given an id, without modifying or returning its value.
void	touch (std::string document_id, std::chrono::system_clock::time_point time_point, const touch_options &options, touch_handler &&handler) const
	Updates the expiration a document given an id, without modifying or returning its value.
auto	touch (std::string document_id, std::chrono::system_clock::time_point time_point, const touch_options &options={}) const -> std::future< std::pair< error, result > >
	Updates the expiration a document given an id, without modifying or returning its value.
void	get_any_replica (std::string document_id, const get_any_replica_options &options, get_any_replica_handler &&handler) const
	Reads all available replicas, and returns the first found.
auto	get_any_replica (std::string document_id, const get_any_replica_options &options={}) const -> std::future< std::pair< error, get_replica_result > >
	Reads all available replicas, and returns the first found.
void	get_all_replicas (std::string document_id, const get_all_replicas_options &options, get_all_replicas_handler &&handler) const
	Reads from all available replicas and the active node and returns the results as a vector.
auto	get_all_replicas (std::string document_id, const get_all_replicas_options &options={}) const -> std::future< std::pair< error, get_all_replicas_result > >
	Reads from all available replicas and the active node and returns the results as a vector.
void	upsert (std::string document_id, codec::encoded_value document, const upsert_options &options, upsert_handler &&handler) const
	Upserts an encoded body of the document which might or might not exist yet, with custom options.
template<typename Transcoder = codec::default_json_transcoder, typename Document>
void	upsert (std::string document_id, Document document, const upsert_options &options, upsert_handler &&handler) const
	Upserts a full document which might or might not exist yet with custom options.
auto	upsert (std::string document_id, codec::encoded_value document, const upsert_options &options) const -> std::future< std::pair< error, mutation_result > >
	Upserts an encoded body of the document which might or might not exist yet, with custom options.
template<typename Transcoder = codec::default_json_transcoder, typename Document>
auto	upsert (std::string document_id, Document document, const upsert_options &options={}) const -> std::future< std::pair< error, mutation_result > >
	Upserts a full document which might or might not exist yet with custom options.
void	insert (std::string document_id, codec::encoded_value document, const insert_options &options, insert_handler &&handler) const
	Inserts an encoded body of the document which does not exist yet with custom options.
template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>
void	insert (std::string document_id, Document document, const insert_options &options, insert_handler &&handler) const
	Inserts a full document which does not exist yet with custom options.
auto	insert (std::string document_id, codec::encoded_value document, const insert_options &options) const -> std::future< std::pair< error, mutation_result > >
	Inserts an encoded body of the document which does not exist yet with custom options.
template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>
auto	insert (std::string document_id, Document document, const insert_options &options={}) const -> std::future< std::pair< error, mutation_result > >
	Inserts a full document which does not exist yet with custom options.
void	replace (std::string document_id, codec::encoded_value document, const replace_options &options, replace_handler &&handler) const
	Replaces a body of the document which already exists with specified encoded body.
template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>
void	replace (std::string document_id, Document document, const replace_options &options, replace_handler &&handler) const
	Replaces a full document which already exists.
auto	replace (std::string document_id, codec::encoded_value document, const replace_options &options) const -> std::future< std::pair< error, mutation_result > >
	Replaces a body of the document which already exists with specified encoded body.
template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>
auto	replace (std::string document_id, Document document, const replace_options &options={}) const -> std::future< std::pair< error, mutation_result > >
	Replaces a full document which already exists.
void	remove (std::string document_id, const remove_options &options, remove_handler &&handler) const
	Removes a Document from a collection.
auto	remove (std::string document_id, const remove_options &options={}) const -> std::future< std::pair< error, mutation_result > >
	Removes a Document from a collection.
void	mutate_in (std::string document_id, const mutate_in_specs &specs, const mutate_in_options &options, mutate_in_handler &&handler) const
	Performs mutations to document fragments.
auto	mutate_in (std::string document_id, const mutate_in_specs &specs, const mutate_in_options &options={}) const -> std::future< std::pair< error, mutate_in_result > >
	Performs mutations to document fragments.
void	lookup_in (std::string document_id, const lookup_in_specs &specs, const lookup_in_options &options, lookup_in_handler &&handler) const
	Performs lookups to document fragments with default options.
auto	lookup_in (std::string document_id, const lookup_in_specs &specs, const lookup_in_options &options={}) const -> std::future< std::pair< error, lookup_in_result > >
	Performs lookups to document fragments with default options.
void	lookup_in_all_replicas (std::string document_id, const lookup_in_specs &specs, const lookup_in_all_replicas_options &options, lookup_in_all_replicas_handler &&handler) const
	Performs lookups to document fragments with default options from all replicas and the active node and returns the result as a vector.
auto	lookup_in_all_replicas (std::string document_id, const lookup_in_specs &specs, const lookup_in_all_replicas_options &options={}) const -> std::future< std::pair< error, lookup_in_all_replicas_result > >
	Performs lookups to document fragments with default options from all replicas and the active node and returns the result as a vector.
void	lookup_in_any_replica (std::string document_id, const lookup_in_specs &specs, const lookup_in_any_replica_options &options, lookup_in_any_replica_handler &&handler) const
	Performs lookups to document fragments with default options from all replicas and returns the first found.
auto	lookup_in_any_replica (std::string document_id, const lookup_in_specs &specs, const lookup_in_any_replica_options &options={}) const -> std::future< std::pair< error, lookup_in_replica_result > >
	Performs lookups to document fragments with default options from all replicas and returns the first found.
void	get_and_lock (std::string document_id, std::chrono::seconds lock_duration, const get_and_lock_options &options, get_and_lock_handler &&handler) const
	Gets a document for a given id and places a pessimistic lock on it for mutations.
auto	get_and_lock (std::string document_id, std::chrono::seconds lock_duration, const get_and_lock_options &options={}) const -> std::future< std::pair< error, get_result > >
	Gets a document for a given id and places a pessimistic lock on it for mutations.
void	unlock (std::string document_id, couchbase::cas cas, const unlock_options &options, unlock_handler &&handler) const
	Unlocks a document if it has been locked previously, with default options.
auto	unlock (std::string document_id, couchbase::cas cas, const unlock_options &options={}) const -> std::future< error >
	Unlocks a document if it has been locked previously, with default options.
void	exists (std::string document_id, const exists_options &options, exists_handler &&handler) const
	Checks if the document exists on the server.
auto	exists (std::string document_id, const exists_options &options={}) const -> std::future< std::pair< error, exists_result > >
	Checks if the document exists on the server.
void	scan (const scan_type &scan_type, const scan_options &options, scan_handler &&handler) const
	Performs a key-value scan operation on the collection.
auto	scan (const scan_type &scan_type, const scan_options &options={}) const -> std::future< std::pair< error, scan_result > >
	Performs a key-value scan operation on the collection.
void	node_id_for (std::string document_id, const node_id_for_options &options, node_id_for_handler &&handler) const
	Resolves a document key to the identity of the cluster node that currently owns it, using the client-side vBucket map (no network round-trip).
auto	node_id_for (std::string document_id, const node_id_for_options &options={}) const -> std::future< std::pair< error, node_id > >
	Resolves a document key to the identity of the cluster node that currently owns it, using the client-side vBucket map (no network round-trip).
void	node_ids (const node_ids_options &options, node_ids_handler &&handler) const
	Returns the set of cluster nodes that currently serve key-value traffic for this collection's bucket, drawn from the client-side topology snapshot (no network round-trip).
auto	node_ids (const node_ids_options &options={}) const -> std::future< std::pair< error, std::vector< node_id > > >
	Returns the set of cluster nodes that currently serve key-value traffic for this collection's bucket, drawn from the client-side topology snapshot (no network round-trip).
auto	query_indexes () const -> collection_query_index_manager

Static Public Attributes
static constexpr auto	default_name { "_default" }
	Constant for the name of the default collection in the bucket.

Friends
class	bucket
class	scope

Detailed Description

The collection provides access to all collection APIs.

Since

1.0.0

Committed

Generally available API and should be preferred in production

Examples

async_game_server.cxx, and game_server.cxx.

Member Function Documentation

binary()

auto binary ( ) const -> binary_collection

nodiscard

Provides access to the binary APIs, not used for JSON documents.

Returns

the requested collection if successful.

Since

1.0.0

Committed

Generally available API and should be preferred in production

bucket_name()

auto bucket_name ( ) const -> const std::string &

nodiscard

Returns name of the bucket where the collection is defined.

Returns

name of the bucket

Since

1.0.0

Committed

Generally available API and should be preferred in production

exists() [1/2]

void exists	(	std::string	document_id,
		const exists_options &	options,
		exists_handler &&	handler ) const

Checks if the document exists on the server.

Parameters

document_id	the id of the document
options	the options to customize
handler	callable that implements exists_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

exists() [2/2]

auto exists ( std::string document_id, const exists_options & options = {} ) const -> std::future< std::pair< error, exists_result > >

nodiscard

Checks if the document exists on the server.

Parameters

document_id	the id of the document
options	the options to customize

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get() [1/2]

void get	(	std::string	document_id,
		const get_options &	options,
		get_handler &&	handler ) const

Fetches the full document from this collection.

Parameters

document_id	the document id which is used to uniquely identify it.
options	options to customize the get request.
handler	the handler that implements get_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get() [2/2]

auto get ( std::string document_id, const get_options & options = {} ) const -> std::future< std::pair< error, get_result > >

nodiscard

Fetches the full document from this collection.

Parameters

document_id	the document id which is used to uniquely identify it.
options	options to customize the get request.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_all_replicas() [1/2]

void get_all_replicas	(	std::string	document_id,
		const get_all_replicas_options &	options,
		get_all_replicas_handler &&	handler ) const

Reads from all available replicas and the active node and returns the results as a vector.

Note

Individual errors are ignored, so you can think of this API as a best effort approach which explicitly emphasises availability over consistency.

Parameters

document_id	the document id which is used to uniquely identify it.
options	the custom options
handler	the handler that implements get_all_replicas_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_all_replicas() [2/2]

auto get_all_replicas ( std::string document_id, const get_all_replicas_options & options = {} ) const -> std::future< std::pair< error, get_all_replicas_result > >

nodiscard

Reads from all available replicas and the active node and returns the results as a vector.

Note

Individual errors are ignored, so you can think of this API as a best effort approach which explicitly emphasises availability over consistency.

Select preferred server group in connection options:

cluster_options.network().preferred_server_group(selected_server_group);

Restrict get_all_replicas to reach nodes that belong to selected server group only:

auto [err, result] = collection
                       .get_all_replicas(id.key(),
                                         couchbase::get_all_replicas_options{}.read_preference(
                                           couchbase::read_preference::selected_server_group))
                       .get();

Parameters

document_id	the document id which is used to uniquely identify it.
options	the custom options

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_lock() [1/2]

void get_and_lock	(	std::string	document_id,
		std::chrono::seconds	lock_duration,
		const get_and_lock_options &	options,
		get_and_lock_handler &&	handler ) const

Gets a document for a given id and places a pessimistic lock on it for mutations.

Parameters

document_id	the id of the document
lock_duration	the length of time the lock will be held on the document
options	the options to customize
handler	callable that implements get_and_lock_handler

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_lock() [2/2]

auto get_and_lock ( std::string document_id, std::chrono::seconds lock_duration, const get_and_lock_options & options = {} ) const -> std::future< std::pair< error, get_result > >

nodiscard

Gets a document for a given id and places a pessimistic lock on it for mutations.

Parameters

document_id	the id of the document
lock_duration	the length of time the lock will be held on the document
options	the options to customize

Returns

future object that carries result of the operation

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_touch() [1/4]

void get_and_touch	(	std::string	document_id,
		std::chrono::seconds	duration,
		const get_and_touch_options &	options,
		get_and_touch_handler &&	handler ) const

Fetches a full document and resets its expiration time to the value provided.

Parameters

document_id	the document id which is used to uniquely identify it.
duration	the new expiration time for the document.
options	custom options to change the default behavior.
handler	the handler that implements get_and_touch_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_touch() [2/4]

auto get_and_touch ( std::string document_id, std::chrono::seconds duration, const get_and_touch_options & options = {} ) const -> std::future< std::pair< error, get_result > >

nodiscard

Fetches a full document and resets its expiration time to the value provided.

Parameters

document_id	the document id which is used to uniquely identify it.
duration	the new expiration time for the document.
options	custom options to change the default behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_touch() [3/4]

void get_and_touch	(	std::string	document_id,
		std::chrono::system_clock::time_point	time_point,
		const get_and_touch_options &	options,
		get_and_touch_handler &&	handler ) const

Fetches a full document and resets its expiration time to the absolute value provided.

Parameters

document_id	the document id which is used to uniquely identify it.
time_point	the new expiration time point for the document.
options	custom options to change the default behavior.
handler	the handler that implements get_and_touch_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_and_touch() [4/4]

auto get_and_touch ( std::string document_id, std::chrono::system_clock::time_point time_point, const get_and_touch_options & options = {} ) const -> std::future< std::pair< error, get_result > >

nodiscard

Fetches a full document and resets its expiration time to the absolute value provided.

Parameters

document_id	the document id which is used to uniquely identify it.
time_point	the new expiration time point for the document.
options	custom options to change the default behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_any_replica() [1/2]

void get_any_replica	(	std::string	document_id,
		const get_any_replica_options &	options,
		get_any_replica_handler &&	handler ) const

Reads all available replicas, and returns the first found.

Parameters

document_id	the document id which is used to uniquely identify it.
options	the custom options
handler	the handler that implements get_any_replica_handler

Exceptions

errc::key_value::document_irretrievable	the situation where the SDK got all responses (most likely: key not found) but none of them were successful so it ended up not returning anything
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

get_any_replica() [2/2]

auto get_any_replica ( std::string document_id, const get_any_replica_options & options = {} ) const -> std::future< std::pair< error, get_replica_result > >

nodiscard

Reads all available replicas, and returns the first found.

Parameters

document_id	the document id which is used to uniquely identify it.
options	the custom options

Returns

the future object with first available result, might be the active or a replica.

Select preferred server group in connection options:

cluster_options.network().preferred_server_group(selected_server_group);

Restrict get_any_replica to reach nodes that belong to selected server group only:

auto [err, result] = collection
                       .get_any_replica(id.key(),
                                        couchbase::get_any_replica_options{}.read_preference(
                                          couchbase::read_preference::selected_server_group))
                       .get();

Exceptions

errc::key_value::document_irretrievable	the situation where the SDK got all responses (most likely: key not found) but none of them were successful so it ended up not returning anything
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

insert() [1/4]

auto insert ( std::string document_id, codec::encoded_value document, const insert_options & options ) const -> std::future< std::pair< error, mutation_result > >

nodiscard

Inserts an encoded body of the document which does not exist yet with custom options.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

insert() [2/4]

void insert	(	std::string	document_id,
		codec::encoded_value	document,
		const insert_options &	options,
		insert_handler &&	handler ) const

Inserts an encoded body of the document which does not exist yet with custom options.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.
handler	callable that implements upsert_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

insert() [3/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>

void insert ( std::string document_id, Document document, const insert_options & options, insert_handler && handler ) const

inline

Inserts a full document which does not exist yet with custom options.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to insert.
options	custom options to customize the insert behavior.
handler	callable that implements insert_handler

Exceptions

errc::key_value::document_exists	the given document id is already present in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

insert() [4/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>

auto insert ( std::string document_id, Document document, const insert_options & options = {} ) const -> std::future< std::pair< error, mutation_result > >

inlinenodiscard

Inserts a full document which does not exist yet with custom options.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to insert.
options	custom options to customize the insert behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_exists	the given document id is already present in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in() [1/2]

void lookup_in	(	std::string	document_id,
		const lookup_in_specs &	specs,
		const lookup_in_options &	options,
		lookup_in_handler &&	handler ) const

Performs lookups to document fragments with default options.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options
handler	callable that implements lookup_in_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in() [2/2]

auto lookup_in ( std::string document_id, const lookup_in_specs & specs, const lookup_in_options & options = {} ) const -> std::future< std::pair< error, lookup_in_result > >

nodiscard

Performs lookups to document fragments with default options.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in_all_replicas() [1/2]

void lookup_in_all_replicas	(	std::string	document_id,
		const lookup_in_specs &	specs,
		const lookup_in_all_replicas_options &	options,
		lookup_in_all_replicas_handler &&	handler ) const

Performs lookups to document fragments with default options from all replicas and the active node and returns the result as a vector.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options
handler	callable that implements lookup_in_all_replicas_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in_all_replicas() [2/2]

auto lookup_in_all_replicas ( std::string document_id, const lookup_in_specs & specs, const lookup_in_all_replicas_options & options = {} ) const -> std::future< std::pair< error, lookup_in_all_replicas_result > >

nodiscard

Performs lookups to document fragments with default options from all replicas and the active node and returns the result as a vector.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in_any_replica() [1/2]

void lookup_in_any_replica	(	std::string	document_id,
		const lookup_in_specs &	specs,
		const lookup_in_any_replica_options &	options,
		lookup_in_any_replica_handler &&	handler ) const

Performs lookups to document fragments with default options from all replicas and returns the first found.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options
handler	callable that implements lookup_in_any_replica_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

lookup_in_any_replica() [2/2]

auto lookup_in_any_replica ( std::string document_id, const lookup_in_specs & specs, const lookup_in_any_replica_options & options = {} ) const -> std::future< std::pair< error, lookup_in_replica_result > >

nodiscard

Performs lookups to document fragments with default options from all replicas and returns the first found.

Parameters

document_id	the outer document ID
specs	an object that specifies the types of lookups to perform
options	custom options to modify the lookup options

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

mutate_in() [1/2]

void mutate_in	(	std::string	document_id,
		const mutate_in_specs &	specs,
		const mutate_in_options &	options,
		mutate_in_handler &&	handler ) const

Performs mutations to document fragments.

Parameters

document_id	the document id which is used to uniquely identify it.
specs	the spec which specifies the type of mutations to perform.
options	custom options to customize the mutate_in behavior.
handler	callable that implements mutate_in_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::key_value::document_exists	the given document id is already present in the collection and insert is was selected.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

mutate_in() [2/2]

auto mutate_in ( std::string document_id, const mutate_in_specs & specs, const mutate_in_options & options = {} ) const -> std::future< std::pair< error, mutate_in_result > >

nodiscard

Performs mutations to document fragments.

Parameters

document_id	the document id which is used to uniquely identify it.
specs	the spec which specifies the type of mutations to perform.
options	custom options to customize the mutate_in behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::key_value::document_exists	the given document id is already present in the collection and insert is was selected.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

name()

auto name ( ) const -> const std::string &

nodiscard

Returns name of the collection.

Returns

name of the collection

Since

1.0.0

Committed

Generally available API and should be preferred in production

node_id_for() [1/2]

void node_id_for	(	std::string	document_id,
		const node_id_for_options &	options,
		node_id_for_handler &&	handler ) const

Resolves a document key to the identity of the cluster node that currently owns it, using the client-side vBucket map (no network round-trip).

Parameters

document_id	the document id to resolve
options	options to customize the request
handler	the handler that receives the result

Since

1.3.2

Uncommitted

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

node_id_for() [2/2]

auto node_id_for ( std::string document_id, const node_id_for_options & options = {} ) const -> std::future< std::pair< error, node_id > >

nodiscard

Resolves a document key to the identity of the cluster node that currently owns it, using the client-side vBucket map (no network round-trip).

Parameters

document_id	the document id to resolve
options	options to customize the request

Returns

future carrying the error (if any) and node_id

Since

1.3.2

Uncommitted

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

node_ids() [1/2]

void node_ids	(	const node_ids_options &	options,
		node_ids_handler &&	handler ) const

Returns the set of cluster nodes that currently serve key-value traffic for this collection's bucket, drawn from the client-side topology snapshot (no network round-trip).

Each entry corresponds to one cluster node and is the same node_id the SDK reports on KV results and errors that touched that node, so the returned set is directly comparable to the keys of any application-side state that is keyed by node_id (e.g. a per-node circuit breaker registry). A periodic sweep that diffs the registry's keys against this set is the canonical way to retire tracker state for a node that has been removed from the cluster topology.

Nodes that do not expose a key-value port for the configured transport (TLS or plain) are excluded from the returned set, since they do not serve KV operations and therefore have no meaningful identity from the SDK's point of view.

Parameters

options	options to customize the request
handler	the handler that receives the result

Since

1.3.2

Uncommitted

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

node_ids() [2/2]

auto node_ids ( const node_ids_options & options = {} ) const -> std::future< std::pair< error, std::vector< node_id > > >

nodiscard

Returns the set of cluster nodes that currently serve key-value traffic for this collection's bucket, drawn from the client-side topology snapshot (no network round-trip).

Parameters

options

options to customize the request

Returns

future carrying the error (if any) and the set of node_ids

Since

1.3.2

Uncommitted

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

query_indexes()

auto query_indexes ( ) const -> collection_query_index_manager

nodiscard

remove() [1/2]

void remove	(	std::string	document_id,
		const remove_options &	options,
		remove_handler &&	handler ) const

Removes a Document from a collection.

Parameters

document_id	the document id which is used to uniquely identify it.
options	custom options to customize the remove behavior.
handler	callable that implements remove_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

remove() [2/2]

auto remove ( std::string document_id, const remove_options & options = {} ) const -> std::future< std::pair< error, mutation_result > >

nodiscard

Removes a Document from a collection.

Parameters

document_id	the document id which is used to uniquely identify it.
options	custom options to customize the remove behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

replace() [1/4]

auto replace ( std::string document_id, codec::encoded_value document, const replace_options & options ) const -> std::future< std::pair< error, mutation_result > >

nodiscard

Replaces a body of the document which already exists with specified encoded body.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

replace() [2/4]

void replace	(	std::string	document_id,
		codec::encoded_value	document,
		const replace_options &	options,
		replace_handler &&	handler ) const

Replaces a body of the document which already exists with specified encoded body.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.
handler	callable that implements upsert_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

replace() [3/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>

void replace ( std::string document_id, Document document, const replace_options & options, replace_handler && handler ) const

inline

Replaces a full document which already exists.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to replace.
options	custom options to customize the replace behavior.
handler	callable that implements replace_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

replace() [4/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document, std::enable_if_t<!std::is_same_v< codec::encoded_value, Document >, bool > = true>

auto replace ( std::string document_id, Document document, const replace_options & options = {} ) const -> std::future< std::pair< error, mutation_result > >

inlinenodiscard

Replaces a full document which already exists.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to replace.
options	custom options to customize the replace behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

scan() [1/2]

void scan	(	const scan_type &	scan_type,
		const scan_options &	options,
		scan_handler &&	handler ) const

Performs a key-value scan operation on the collection.

Parameters

scan_type	the type of the scan. Can be range_scan, prefix_scan or sampling_scan
options	the options to customize
handler	callable that implements scan_handler

Note

Use this API for low concurrency batch queries where latency is not critical as the system may have to scan a lot of documents to find the matching documents. For low latency range queries, it is recommended that you use SQL++ with the necessary indexes.

Since

1.0.0

Volatile

Should not be used in production

scan() [2/2]

auto scan ( const scan_type & scan_type, const scan_options & options = {} ) const -> std::future< std::pair< error, scan_result > >

nodiscard

Performs a key-value scan operation on the collection.

Parameters

scan_type	the type of the scan. Can be range_scan, prefix_scan or sampling_scan
options	the options to customize

Returns

future object that carries result of the operation

Note

Use this API for low concurrency batch queries where latency is not critical as the system may have to scan a lot of documents to find the matching documents. For low latency range queries, it is recommended that you use SQL++ with the necessary indexes.

Since

1.0.0

Volatile

Should not be used in production

scope_name()

auto scope_name ( ) const -> const std::string &

nodiscard

Returns name of the scope where the collection is defined.

Returns

name of the scope

Since

1.0.0

Committed

Generally available API and should be preferred in production

touch() [1/4]

void touch	(	std::string	document_id,
		std::chrono::seconds	duration,
		const touch_options &	options,
		touch_handler &&	handler ) const

Updates the expiration a document given an id, without modifying or returning its value.

Parameters

document_id	the document id which is used to uniquely identify it.
duration	the new expiration time for the document.
options	custom options to change the default behavior.
handler	the handler that implements touch_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

touch() [2/4]

auto touch ( std::string document_id, std::chrono::seconds duration, const touch_options & options = {} ) const -> std::future< std::pair< error, result > >

nodiscard

Updates the expiration a document given an id, without modifying or returning its value.

Parameters

document_id	the document id which is used to uniquely identify it.
duration	the new expiration time for the document.
options	custom options to change the default behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

touch() [3/4]

void touch	(	std::string	document_id,
		std::chrono::system_clock::time_point	time_point,
		const touch_options &	options,
		touch_handler &&	handler ) const

Updates the expiration a document given an id, without modifying or returning its value.

Parameters

document_id	the document id which is used to uniquely identify it.
time_point	the new expiration time point for the document.
options	custom options to change the default behavior.
handler	the handler that implements touch_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

touch() [4/4]

auto touch ( std::string document_id, std::chrono::system_clock::time_point time_point, const touch_options & options = {} ) const -> std::future< std::pair< error, result > >

nodiscard

Updates the expiration a document given an id, without modifying or returning its value.

Parameters

document_id	the document id which is used to uniquely identify it.
time_point	the new expiration time point for the document.
options	custom options to change the default behavior.

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

unlock() [1/2]

void unlock	(	std::string	document_id,
		couchbase::cas	cas,
		const unlock_options &	options,
		unlock_handler &&	handler ) const

Unlocks a document if it has been locked previously, with default options.

Parameters

document_id	the id of the document
cas	the CAS value which is needed to unlock it
options	the options to customize
handler	callable that implements unlock_handler

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

unlock() [2/2]

auto unlock ( std::string document_id, couchbase::cas cas, const unlock_options & options = {} ) const -> std::future< error >

nodiscard

Unlocks a document if it has been locked previously, with default options.

Parameters

document_id	the id of the document
cas	the CAS value which is needed to unlock it
options	the options to customize

Returns

future object that carries result of the operation

Exceptions

errc::key_value::document_not_found	the given document id is not found in the collection.
errc::common::cas_mismatch	if the document has been concurrently modified on the server.
errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

upsert() [1/4]

auto upsert ( std::string document_id, codec::encoded_value document, const upsert_options & options ) const -> std::future< std::pair< error, mutation_result > >

nodiscard

Upserts an encoded body of the document which might or might not exist yet, with custom options.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

upsert() [2/4]

void upsert	(	std::string	document_id,
		codec::encoded_value	document,
		const upsert_options &	options,
		upsert_handler &&	handler ) const

Upserts an encoded body of the document which might or might not exist yet, with custom options.

Parameters

document_id	the document id which is used to uniquely identify it.
document	the encoded content of the document to upsert.
options	custom options to customize the upsert behavior.
handler	callable that implements upsert_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Uncommitted

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

Examples

async_game_server.cxx, distributed_mutex.cxx, and game_server.cxx.

upsert() [3/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document>

void upsert ( std::string document_id, Document document, const upsert_options & options, upsert_handler && handler ) const

inline

Upserts a full document which might or might not exist yet with custom options.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to upsert.
options	custom options to customize the upsert behavior.
handler	callable that implements upsert_handler

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

upsert() [4/4]

template<typename Transcoder = codec::default_json_transcoder, typename Document>

auto upsert ( std::string document_id, Document document, const upsert_options & options = {} ) const -> std::future< std::pair< error, mutation_result > >

inlinenodiscard

Upserts a full document which might or might not exist yet with custom options.

Template Parameters

Transcoder	type of the transcoder that will be used to encode the document
Document	type of the document

Parameters

document_id	the document id which is used to uniquely identify it.
document	the document content to upsert.
options	custom options to customize the upsert behavior.

Returns

future object that carries result of the operation

Exceptions

errc::common::ambiguous_timeout
errc::common::unambiguous_timeout

Since

1.0.0

Committed

Generally available API and should be preferred in production

Friends And Related Symbol Documentation

bucket

friend class bucket

friend

Examples

distributed_mutex.cxx.

scope

friend class scope

friend

Member Data Documentation

default_name

auto default_name { "_default" }

staticconstexpr

Constant for the name of the default collection in the bucket.

Since

1.0.0

Committed

Generally available API and should be preferred in production

Examples

distributed_mutex.cxx, and minimal.cxx.

---

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

• couchbase/collection.hxx