Couchbase C Client  3.2.0
Asynchronous C Client for Couchbase

Detailed Description

Set the value of a document.


lcb_STATUS lcb_respstore_status (const lcb_RESPSTORE *resp)
lcb_STATUS lcb_respstore_error_context (const lcb_RESPSTORE *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
lcb_STATUS lcb_respstore_cookie (const lcb_RESPSTORE *resp, void **cookie)
lcb_STATUS lcb_respstore_cas (const lcb_RESPSTORE *resp, uint64_t *cas)
lcb_STATUS lcb_respstore_key (const lcb_RESPSTORE *resp, const char **key, size_t *key_len)
lcb_STATUS lcb_respstore_operation (const lcb_RESPSTORE *resp, lcb_STORE_OPERATION *operation)
lcb_STATUS lcb_respstore_mutation_token (const lcb_RESPSTORE *resp, lcb_MUTATION_TOKEN *token)
int lcb_respstore_observe_attached (const lcb_RESPSTORE *resp)
lcb_STATUS lcb_respstore_observe_stored (const lcb_RESPSTORE *resp, int *store_ok)
lcb_STATUS lcb_respstore_observe_master_exists (const lcb_RESPSTORE *resp, int *master_exists)
lcb_STATUS lcb_respstore_observe_master_persisted (const lcb_RESPSTORE *resp, int *master_persisted)
lcb_STATUS lcb_respstore_observe_num_responses (const lcb_RESPSTORE *resp, uint16_t *num_responses)
lcb_STATUS lcb_respstore_observe_num_persisted (const lcb_RESPSTORE *resp, uint16_t *num_persisted)
lcb_STATUS lcb_respstore_observe_num_replicated (const lcb_RESPSTORE *resp, uint16_t *num_replicated)
lcb_STATUS lcb_cmdstore_create (lcb_CMDSTORE **cmd, lcb_STORE_OPERATION operation)
lcb_STATUS lcb_cmdstore_destroy (lcb_CMDSTORE *cmd)
lcb_STATUS lcb_cmdstore_parent_span (lcb_CMDSTORE *cmd, lcbtrace_SPAN *span)
lcb_STATUS lcb_cmdstore_collection (lcb_CMDSTORE *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
lcb_STATUS lcb_cmdstore_key (lcb_CMDSTORE *cmd, const char *key, size_t key_len)
lcb_STATUS lcb_cmdstore_value (lcb_CMDSTORE *cmd, const char *value, size_t value_len)
lcb_STATUS lcb_cmdstore_value_iov (lcb_CMDSTORE *cmd, const lcb_IOV *value, size_t value_len)
lcb_STATUS lcb_cmdstore_expiry (lcb_CMDSTORE *cmd, uint32_t expiration)
lcb_STATUS lcb_cmdstore_preserve_expiry (lcb_CMDSTORE *cmd, int should_preserve)
lcb_STATUS lcb_cmdstore_cas (lcb_CMDSTORE *cmd, uint64_t cas)
lcb_STATUS lcb_cmdstore_flags (lcb_CMDSTORE *cmd, uint32_t flags)
lcb_STATUS lcb_cmdstore_datatype (lcb_CMDSTORE *cmd, uint8_t datatype)
lcb_STATUS lcb_cmdstore_durability (lcb_CMDSTORE *cmd, lcb_DURABILITY_LEVEL level)
lcb_STATUS lcb_cmdstore_durability_observe (lcb_CMDSTORE *cmd, int persist_to, int replicate_to)
lcb_STATUS lcb_cmdstore_timeout (lcb_CMDSTORE *cmd, uint32_t timeout)
lcb_STATUS lcb_store (lcb_INSTANCE *instance, void *cookie, const lcb_CMDSTORE *cmd)


typedef struct lcb_RESPSTORE_ lcb_RESPSTORE
Schedule a single storage request More...
typedef struct lcb_CMDSTORE_ lcb_CMDSTORE


 Values for lcb_CMDSTORE::operation. More...

Typedef Documentation


typedef struct lcb_RESPSTORE_ lcb_RESPSTORE

Schedule a single storage request

instancethe handle
cookiepointer to associate with the command
cmdthe command structure
LCB_SUCCESS on success, error code on failure


lcb_CMDSTORE* cmd;
// insert only if key doesn't already exist
lcb_cmdstore_create(&cmd, LCB_STORE_INSERT);
lcb_cmdstore_key(cmd, "Key", 3);
lcb_cmdstore_value(cmd, "value", 5);
lcb_cmdstore_expiry(cmd, 60); // expire in a minute
lcb_store(instance, cookie, &cmd);

### Response

lcb_install_callback(instance, LCB_CALLBACK_STORE, store_callback);
void store_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *rb)
uint64_t cas;
const lcb_RESPSTORE resp = (const lcb_RESPSTORE*)rb;
lcb_STATUS rc = lcb_respstore_status(resp);
if (rc == LCB_SUCCESS) {
lcb_respstore_cas(resp, &cas)
printf("Store success: CAS=%llx\n", cas);
} else {
printf("Store failed: %s\n", lcb_strerror_short(rc);

Operation-specific error codes include:

  • ::LCB_ERR_DOCUMENT_NOT_FOUND if ::LCB_REPLACE was used and the key does not exist
  • ::LCB_ERR_DOCUMENT_EXISTS if ::LCB_INSERT was used and the key already exists
  • ::LCB_ERR_DOCUMENT_EXISTS if the CAS was specified (for an operation other than ::LCB_INSERT) and the item exists on the server with a different CAS
  • ::LCB_ERR_DOCUMENT_EXISTS if the item was locked and the CAS supplied did not match the locked item's CAS (or if no CAS was supplied)
  • ::LCB_ERR_NOT_STORED if an ::LCB_APPEND or ::LCB_PREPEND operation was performed and the item did not exist on the server.
  • ::LCB_ERR_VALUE_TOO_LARGE if the size of the value exceeds the cluster per-item value limit (currently 20MB).

For a 6.5 or later cluster, you should use the lcb_cmdstore_durability to make the lcb_store not return until the requested durabilty is met. If the cluster is an older version, you can use lcb_cmdstore_durability_observe.

Enumeration Type Documentation


Values for lcb_CMDSTORE::operation.

Storing an item in couchbase is only one operation with a different set of attributes / constraints.


The default storage mode.

This constant was added in version 2.6.2 for the sake of maintaining a default storage mode, eliminating the need for simple storage operations to explicitly define lcb_CMDSTORE::operation. Behaviorally it is identical to LCB_STORE_UPSERT in that it will make the server unconditionally store the item, whether it exists or not.


Will cause the operation to fail if the key already exists in the cluster.


Will cause the operation to fail unless the key already exists in the cluster.


Rather than setting the contents of the entire document, take the value specified in lcb_CMDSTORE::value and append it to the existing bytes in the value.


Like LCB_STORE_APPEND, but prepends the new value to the existing value.