Couchbase C++ SDK 1.0.2 (rev. 51f4775)
Loading...
Searching...
No Matches
attempt_context Class Referenceabstract

The attempt_context is used for all synchronous transaction operations. More...

#include <couchbase/transactions/attempt_context.hxx>

Public Member Functions

virtual auto get (const couchbase::collection &coll, const std::string &id) -> std::pair< error, transaction_get_result >=0
 Get a document from a collection.
 
virtual auto get_replica_from_preferred_server_group (const couchbase::collection &coll, const std::string &id) -> std::pair< error, transaction_get_result >=0
 Get a document copy from the selected server group.
 
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 (const couchbase::collection &coll, const std::string &id, const Document &content) -> std::pair< error, transaction_get_result >
 Insert a document into a collection.
 
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 (const transaction_get_result &doc, const Document &content) -> std::pair< error, transaction_get_result >
 Replace the contents of a document in a collection.
 
virtual auto remove (const transaction_get_result &doc) -> error=0
 Remove a document.
 
auto query (const std::string &statement, const transaction_query_options &options={}) -> std::pair< error, transaction_query_result >
 Perform an unscoped query.
 
auto query (const scope &scope, const std::string &statement, const transaction_query_options &opts={}) -> std::pair< error, transaction_query_result >
 Perform a scoped query.
 
virtual ~attempt_context ()=default
 

Detailed Description

The attempt_context is used for all synchronous transaction operations.

In the example below, we get a document then replace its content:

auto [tx_err, tx_res] = cluster.transactions()->run(
// [3.1] closure argument to run() method encapsulates logic, that has to be run in
// transaction
[=](std::shared_ptr<couchbase::transactions::attempt_context> ctx) -> couchbase::error {
// [3.2] get document
auto [err_ctx, doc] = ctx->get(collection, id_1);
if (err_ctx.ec()) {
fmt::print(stderr, "failed to get document \"{}\": {}\n", id_1, err_ctx.ec().message());
// [3.3] don't continue the transaction logic
return {};
}
// [3.4] replace document's content
ctx->replace(doc, tao::json::value{ { "some", "other content" } });
return {};
});
// [3.5] check the overall status of the transaction
if (tx_err.ec()) {
fmt::print(stderr,
"error in transaction {}, cause: {}\n",
tx_err.ec().message(),
tx_err.cause().has_value() ? tx_err.cause().value().ec().message() : "");
retval = 1;
} else {
fmt::print("transaction {} completed successfully\n", tx_res.transaction_id);
}

Constructor & Destructor Documentation

◆ ~attempt_context()

virtual ~attempt_context ( )
virtualdefault

Member Function Documentation

◆ get()

virtual auto get ( const couchbase::collection & coll,
const std::string & id ) -> std::pair< error, transaction_get_result >
pure virtual

Get a document from a collection.

Fetch the document contents, in the form of a transaction_get_result. This can be used in subsequent calls to attempt_context::replace or attempt_context::remove

Parameters
collThe collection which contains the document.
idThe unique id of the document.
Returns
The result of the operation, which is an error and a transaction_get_result.

The example below shows how to use custom transcoder with transactions.

The type should have transcoder to be defined. The only restriction is that the transcoder should mark encoded value with either codec::codec_flags::json_common_flags or codec::codec_flags::binary_common_flags. Behavior of transcoders with any other flags is not defined.

auto [err_ctx, doc] = ctx->get(collection, "the_ledger");
if (err_ctx.ec()) {
fmt::print(stderr, "Failed to retrieve \"the_ledger\": {}\n", err_ctx.ec().message());
return {};
}
// decode binary object into an application struct
auto the_ledger = doc.content_as<ledger, csv_transcoder>();
See also
transactions::transaction_get_result for more complete example

◆ get_replica_from_preferred_server_group()

virtual auto get_replica_from_preferred_server_group ( const couchbase::collection & coll,
const std::string & id ) -> std::pair< error, transaction_get_result >
pure virtual

Get a document copy from the selected server group.

Fetch the document contents, in the form of a transaction_get_result. It might be either replica or active copy of the document. One of the use cases for this method is to save on network costs by deploying SDK in the same availability zone as corresponding server group of the nodes.

Parameters
collThe collection which contains the document.
idThe unique id of the document.
Returns
The result of the operation, which is an error and a transaction_get_result.

Select preferred server group in connection options:

cluster_options.network().preferred_server_group(selected_server_group);

Fetch document from the nodes that belong to selected server group only:

auto [tx_err, tx_res] = cluster.transactions()->run(
[=](std::shared_ptr<couchbase::transactions::attempt_context> ctx) -> couchbase::error {
auto [err, doc] = ctx->get_replica_from_preferred_server_group(collection, id);
if (err) {
fmt::println(stderr, "failed to get document \"{}\": {}", id, err.ec().message());
return {};
}
fmt::println("document content: {}",
tao::json::to_string(doc.template content_as<tao::json::value>()));
return {};
});
if (tx_err.ec()) {
fmt::println(stderr,
"error in transaction {}, cause: {}",
tx_err.ec().message(),
tx_err.cause().has_value() ? tx_err.cause().value().ec().message() : "");
retval = 1;
} else {
fmt::println("transaction {} completed successfully", tx_res.transaction_id);
}
See also
network_options::preferred_server_group
https://docs.couchbase.com/server/current/manage/manage-groups/manage-groups.html

◆ insert()

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 ( const couchbase::collection & coll,
const std::string & id,
const Document & content ) -> std::pair<error, transaction_get_result>
inline

Insert a document into a collection.

Given an id and the content, this inserts a new document into a collection. Note that currently this content can be either a <std::vector<std::byte>> or an object which can be serialized with the codec::tao_json_serializer.

Template Parameters
DocumentType of the contents of the document.
Parameters
collCollection in which to insert document.
idThe unique id of the document.
contentThe content of the document.
Returns
The result of the operation, which is an error and a transaction_get_result.

◆ query() [1/2]

auto query ( const scope & scope,
const std::string & statement,
const transaction_query_options & opts = {} ) -> std::pair< error, transaction_query_result >

Perform a scoped query.

Parameters
scopeScope for the query.
statementThe query statement.
optsOptions for the query.
Returns
The result of the operation, with is an error and a transaction_query_result.

◆ query() [2/2]

auto query ( const std::string & statement,
const transaction_query_options & options = {} ) -> std::pair< error, transaction_query_result >

Perform an unscoped query.

Parameters
statementThe query statement.
optionsOptions for the query.
Returns
The result of the operation, with is an error and a transaction_query_result.

◆ remove()

virtual auto remove ( const transaction_get_result & doc) -> error
pure virtual

Remove a document.

Removes a document from a collection, where the document was gotten from a previous call to attempt_context::get

Parameters
docThe document to remove.
Returns
The result of the operation.

◆ replace()

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 ( const transaction_get_result & doc,
const Document & content ) -> std::pair<error, transaction_get_result>
inline

Replace the contents of a document in a collection.

Replaces the contents of an existing document. Note that currently this content can be either a std::vector<std::byte> or an object which can be serialized with the codec::tao_json_serializer.

Template Parameters
ContentType of the contents of the document.
Parameters
docDocument whose content will be replaced. This is gotten from a call to attempt_context::get
contentNew content of the document.
Returns
The result of the operation, which is an error and a transaction_get_result.

The example below shows how to use custom transcoder with transactions.

The type should have transcoder to be defined. The only restriction is that the transcoder should mark encoded value with either codec::codec_flags::json_common_flags or codec::codec_flags::binary_common_flags. Behavior of transcoders with any other flags is not defined.

auto [err_ctx, doc] = ctx->get(collection, "the_ledger");
if (err_ctx.ec()) {
fmt::print(stderr, "Failed to retrieve \"the_ledger\": {}\n", err_ctx.ec().message());
return {};
}
// decode binary object into an application struct
auto the_ledger = doc.content_as<ledger, csv_transcoder>();
the_ledger.add_record("2024-09-01", "Cash", "Expenses", 1000, "Rent payment");
// replace the document contents, that will be treated by Couchbase as a binary object
ctx->replace<csv_transcoder, ledger>(doc, the_ledger);
See also
transactions::transaction_get_result for more complete example

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