Create/Update

Detailed Description

Set the value of a document.

Functions
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_cmdstore_on_behalf_of (lcb_CMDSTORE *cmd, const char *data, size_t data_len)
lcb_STATUS	lcb_cmdstore_on_behalf_of_extra_privilege (lcb_CMDSTORE *cmd, const char *privilege, size_t privilege_len)
lcb_STATUS	lcb_store (lcb_INSTANCE *instance, void *cookie, const lcb_CMDSTORE *cmd)

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

Enumerations
enum	lcb_STORE_OPERATION
	Values for lcb_CMDSTORE::operation. More...

Function Documentation

lcb_cmdstore_on_behalf_of()

lcb_STATUS lcb_cmdstore_on_behalf_of	(	lcb_CMDSTORE *	cmd,
		const char *	data,
		size_t	data_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_cmdstore_on_behalf_of_extra_privilege()

lcb_STATUS lcb_cmdstore_on_behalf_of_extra_privilege	(	lcb_CMDSTORE *	cmd,
		const char *	privilege,
		size_t	privilege_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

Typedef Documentation

lcb_RESPSTORE

typedef struct lcb_RESPSTORE_ lcb_RESPSTORE

Schedule a single storage request.

Stability

Committed:

Parameters

instance	the handle
cookie	pointer to associate with the command
cmd	the command structure

Returns

LCB_SUCCESS on success, error code on failure

Request

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);
lcb_wait(instance, LCB_WAIT_NOCHECK);

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

lcb_STORE_OPERATION

enum lcb_STORE_OPERATION

Values for lcb_CMDSTORE::operation.

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

Enumerator
LCB_STORE_UPSERT	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.
LCB_STORE_INSERT	Will cause the operation to fail if the key already exists in the cluster.
LCB_STORE_REPLACE	Will cause the operation to fail unless the key already exists in the cluster.
LCB_STORE_APPEND	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.
LCB_STORE_PREPEND	Like LCB_STORE_APPEND, but prepends the new value to the existing value.