Couchbase C Client  2.10.0
Asynchronous C Client for Couchbase
Read (Replica)

Detailed Description

Retrieve a document from a replica if it cannot be fetched from the primary.


lcb_error_t lcb_rget3 (lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd)
 Spool a single get-with-replica request. More...


enum  lcb_replica_t
 Select get-replica mode. More...

Function Documentation

◆ lcb_rget3()

lcb_error_t lcb_rget3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDGETREPLICA cmd 

Spool a single get-with-replica request.

LCB_SUCCESS on success, error code otherwise.

When a response is received, the callback installed for LCB_CALLBACK_GETREPLICA will be invoked. The response will be an lcb_RESPGET pointer.

### Request

lcb_CMDGETREPLICA cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key", 3);
lcb_rget3(instance, cookie, &cmd);

### Response

static void rget_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
const lcb_RESPGET *resp = (const lcb_RESPGET *)rb;
printf("Got Get-From-Replica response for %.*s\n", (int)resp->key, resp->nkey);
if (resp->rc == LCB_SUCCESS) {
printf("Got response: %.*s\n", (int)resp->value, resp->nvalue);
else {
printf("Couldn't retrieve: %s\n", lcb_strerror(NULL, resp->rc));
As this function queries a replica node for data it is possible that the returned document may not reflect the latest document in the server.
This function should only be used in cases where a normal lcb_get3() has failed, or where there is reason to believe it will fail. Because this function may query more than a single replica it may cause additional network and server-side CPU load. Use sparingly and only when necessary.

Data Structure Documentation



Command for requesting an item from a replica.

The options.exptime and options.cas fields are ignored for this command.

This structure is similar to lcb_RESPGET with the addition of an index and strategy field which allow you to control and select how many replicas are queried.

See also
lcb_rget3(), lcb_RESPGET
Data Fields
lcb_U32 cmdflags Common flags for the command.

These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.

lcb_U32 exptime Specify the expiration time.

This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.

lcb_U64 cas The known CAS of the item.

This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.

lcb_KEYBUF key The key for the document itself.

This should be set via LCB_CMD_SET_KEY()

lcb_KEYBUF _hashkey
lcb_replica_t strategy Strategy for selecting a replica.

The default is LCB_REPLICA_FIRST which results in the client trying each replica in sequence until a successful reply is found, and returned in the callback.

LCB_REPLICA_FIRST evaluates to 0.

Other options include:

When LCB_REPLICA_ALL is selected, the callback will be invoked multiple times, one for each replica. The final callback will have the LCB_RESP_F_FINAL bit set in the lcb_RESPBASE::rflags field. The final response will also contain the response from the last replica to respond.
int index Valid only when strategy is LCB_REPLICA_SELECT, specifies the replica index number to query.

This should be no more than nreplicas-1 where nreplicas is the number of replicas the bucket is configured with.

Enumeration Type Documentation

◆ lcb_replica_t

Select get-replica mode.

See also

Query all the replicas sequentially, retrieving the first successful response.


Query all the replicas concurrently, retrieving all the responses.


Query the specific replica specified by the lcb_rget3_cmd_t::index field.