Couchbase C++ SDK 1.0.2 (rev. 51f4775)
Loading...
Searching...
No Matches
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, const 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, const 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, const 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.
 
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, distributed_mutex.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_idthe id of the document
optionsthe options to customize
handlercallable 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_idthe id of the document
optionsthe 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_idthe document id which is used to uniquely identify it.
optionsoptions to customize the get request.
handlerthe handler that implements get_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
optionsoptions to customize the get request.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
optionsthe custom options
handlerthe 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(),
.get();
Parameters
document_idthe document id which is used to uniquely identify it.
optionsthe 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_idthe id of the document
lock_durationthe length of time the lock will be held on the document
optionsthe options to customize
handlercallable 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_idthe id of the document
lock_durationthe length of time the lock will be held on the document
optionsthe 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_idthe document id which is used to uniquely identify it.
durationthe new expiration time for the document.
optionscustom options to change the default behavior.
handlerthe handler that implements get_and_touch_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
durationthe new expiration time for the document.
optionscustom options to change the default behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
time_pointthe new expiration time point for the document.
optionscustom options to change the default behavior.
handlerthe handler that implements get_and_touch_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
time_pointthe new expiration time point for the document.
optionscustom options to change the default behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
optionsthe custom options
handlerthe handler that implements get_any_replica_handler
Exceptions
errc::key_value::document_irretrievablethe 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_idthe document id which is used to uniquely identify it.
optionsthe 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(),
.get();
Exceptions
errc::key_value::document_irretrievablethe 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom options to customize the upsert behavior.
handlercallable 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>
auto insert ( std::string document_id,
const 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
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to insert.
optionscustom options to customize the insert behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_existsthe 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>
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
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to insert.
optionscustom options to customize the insert behavior.
handlercallable that implements insert_handler
Exceptions
errc::key_value::document_existsthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
handlercallable that implements lookup_in_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
handlercallable that implements lookup_in_all_replicas_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
handlercallable that implements lookup_in_any_replica_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe outer document ID
specsan object that specifies the types of lookups to perform
optionscustom options to modify the lookup options
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
specsthe spec which specifies the type of mutations to perform.
optionscustom options to customize the mutate_in behavior.
handlercallable that implements mutate_in_handler
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::key_value::document_existsthe given document id is already present in the collection and insert is was selected.
errc::common::cas_mismatchif 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_idthe document id which is used to uniquely identify it.
specsthe spec which specifies the type of mutations to perform.
optionscustom options to customize the mutate_in behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::key_value::document_existsthe given document id is already present in the collection and insert is was selected.
errc::common::cas_mismatchif 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

◆ 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_idthe document id which is used to uniquely identify it.
optionscustom options to customize the remove behavior.
handlercallable that implements remove_handler
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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_idthe document id which is used to uniquely identify it.
optionscustom options to customize the remove behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom options to customize the upsert behavior.
handlercallable 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>
auto replace ( std::string document_id,
const Document & document,
const replace_options & options = {} ) const -> std::future<std::pair<error, mutation_result>>
inlinenodiscard

Replaces a full document which already exists.

Template Parameters
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to replace.
optionscustom options to customize the replace behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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>
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
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to replace.
optionscustom options to customize the replace behavior.
handlercallable that implements replace_handler
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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_typethe type of the scan. Can be range_scan, prefix_scan or sampling_scan
optionsthe options to customize
handlercallable 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_typethe type of the scan. Can be range_scan, prefix_scan or sampling_scan
optionsthe 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_idthe document id which is used to uniquely identify it.
durationthe new expiration time for the document.
optionscustom options to change the default behavior.
handlerthe handler that implements touch_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
durationthe new expiration time for the document.
optionscustom options to change the default behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
time_pointthe new expiration time point for the document.
optionscustom options to change the default behavior.
handlerthe handler that implements touch_handler
Exceptions
errc::key_value::document_not_foundthe 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_idthe document id which is used to uniquely identify it.
time_pointthe new expiration time point for the document.
optionscustom options to change the default behavior.
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe 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_idthe id of the document
casthe CAS value which is needed to unlock it
optionsthe options to customize
handlercallable that implements unlock_handler
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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_idthe id of the document
casthe CAS value which is needed to unlock it
optionsthe options to customize
Returns
future object that carries result of the operation
Exceptions
errc::key_value::document_not_foundthe given document id is not found in the collection.
errc::common::cas_mismatchif 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom 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_idthe document id which is used to uniquely identify it.
documentthe encoded content of the document to upsert.
optionscustom options to customize the upsert behavior.
handlercallable 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 >
auto upsert ( std::string document_id,
const 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
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to upsert.
optionscustom 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

◆ upsert() [4/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
Transcodertype of the transcoder that will be used to encode the document
Documenttype of the document
Parameters
document_idthe document id which is used to uniquely identify it.
documentthe document content to upsert.
optionscustom options to customize the upsert behavior.
handlercallable 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

Friends And Related Symbol Documentation

◆ bucket

friend class bucket
friend

◆ 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: