Couchbase C Client  2.9.4
Asynchronous C Client for Couchbase
Sub-Document API

Detailed Description

Experimental in-document API access.

The sub-document API uses features from the upcoming Couchbase 4.5 release which allows access to parts of the document. These parts are called sub-documents and can be accessed using the sub-document API


lcb_error_t lcb_subdoc3 (lcb_t instance, const void *cookie, const lcb_CMDSUBDOC *cmd)
 Perform one or more subdocument operations.
int lcb_sdresult_next (const lcb_RESPSUBDOC *resp, lcb_SDENTRY *out, size_t *iter)
 Iterate over the results for a subdocument response. More...


 Create intermediate paths.
 Access document XATTR path.
 Access document virtual/materialized path. More...
 Access Xattrs of deleted documents.
#define LCB_SDSPEC_SET_PATH(s, p, n)
 Set the path for an lcb_SDSPEC structure. More...
#define LCB_SDSPEC_SET_VALUE(s, v, n)
 Set the value for the lcb_SDSPEC structure. More...
#define LCB_SDSPEC_INIT(spec, cmd_, path_, npath_, val_, nval_)
 This command flag should be used if the document is to be created if it does not exist.
 This command flag should be used if the document must be created anew. More...
 Access a potentially deleted document. More...


enum  lcb_SUBDOCOP
 Sub-Document command codes. More...

Function Documentation

◆ lcb_sdresult_next()

int lcb_sdresult_next ( const lcb_RESPSUBDOC resp,
lcb_SDENTRY out,
size_t *  iter 

Iterate over the results for a subdocument response.

This function must be called from within the callback. The response itself may contain a pointer to internal stack data which is no longer valid once the callback exits.
respthe response received from within the callback.
[out]outstructure to store the current result
[in,out]iterinternal iterator. First call should initialize this to 0 Note that this value may be 0, in which case only the first response is returned.
If this function returns nonzero then out will contain a valid entry. If this function returns 0 then ent is invalid and no more results remain for the response.

Data Structure Documentation

◆ lcb_SDSPEC

struct lcb_SDSPEC

Subdoc command specification.

This structure describes an operation and its path, and possibly its value. This structure is provided in an array to the lcb_CMDSUBDOC::specs field.

Data Fields
lcb_U32 sdcmd The command code, lcb_SUBDOCOP.

There is no default for this value, and it therefore must be set.

lcb_U32 options Set of option flags for the command.

Currently the only option known is LCB_SDSPEC_F_MKINTERMEDIATES

lcb_KEYBUF path Path for the operation.

This should be assigned using LCB_SDSPEC_SET_PATH. The contents of the path should be valid until the operation is scheduled (lcb_subdoc3())

lcb_VALBUF value Value for the operation.

This should be assigned using LCB_SDSPEC_SET_VALUE. The contents of the value should be valid until the operation is scheduled (i.e. lcb_subdoc3())


struct lcb_RESPSUBDOC

Response structure for multi lookups.

If the top level response is successful then the individual results may be retrieved using lcb_sdmlookup_next()

Data Fields
LCB_RESP_BASE const void * responses
void * bufh Use with lcb_backbuf_ref/unref.


struct lcb_SDENTRY

Structure for a single sub-document mutation or lookup result.

Note that value and nvalue are only valid if status is LCB_SUCCESS

Data Fields
const void * value Value for the mutation (only applicable for LCB_SDCMD_COUNTER, currently)
size_t nvalue Length of the value.
lcb_error_t status Status code.
lcb_U8 index Request index which this result pertains to.

This field only makes sense for multi mutations where not all request specs are returned in the result

Macro Definition Documentation



Access document virtual/materialized path.



#define LCB_SDSPEC_SET_PATH (   s,

Set the path for an lcb_SDSPEC structure.

spointer to spec
pthe path buffer
nthe length of the path buffer


#define LCB_SDSPEC_SET_VALUE (   s,

Set the value for the lcb_SDSPEC structure.

spointer to spec
vthe value buffer
nthe length of the value buffer



This command flag should be used if the document must be created anew.

In this case, it will fail if it already exists



Access a potentially deleted document.

For internal Couchbase use

Enumeration Type Documentation


Sub-Document command codes.

These command codes should be applied as values to lcb_SDSPEC::sdcmd and indicate which type of subdoc command the server should perform.


Retrieve the value for a path.


Check if the value for a path exists.

If the path exists then the error code will be LCB_SUCCESS


Replace the value at the specified path.

This operation can work on any existing and valid path.


Add the value at the given path, if the given path does not exist.

The penultimate path component must point to an array. The operation may be used in conjunction with LCB_SDSPEC_F_MKINTERMEDIATES to create the parent dictionary (and its parents as well) if it does not yet exist.


Unconditionally set the value at the path.

This logically attempts to perform a LCB_SDCMD_REPLACE, and if it fails, performs an LCB_SDCMD_DICT_ADD.


Prepend the value(s) to the array indicated by the path.

The path should reference an array. When the LCB_SDSPEC_F_MKINTERMEDIATES flag is specified then the array may be created if it does not exist.

Note that it is possible to add more than a single value to an array in an operation (this is valid for this commnand as well as LCB_SDCMD_ARRAY_ADD_LAST and LCB_SDCMD_ARRAY_INSERT). Multiple items can be specified by placing a comma between then (the values should otherwise be valid JSON).


Identical to LCB_SDCMD_ARRAY_ADD_FIRST but places the item(s) at the end of the array rather than at the beginning.


Add the value to the array indicated by the path, if the value is not already in the array.

The LCB_SDSPEC_F_MKINTERMEDIATES flag can be specified to create the array if it does not already exist.

Currently the value for this operation must be a JSON primitive (i.e. no arrays or dictionaries) and the existing array itself must also contain only primitives (otherwise a LCB_SUBDOC_PATH_MISMATCH error will be received).


Add the value at the given array index.

Unlike other array operations, the path specified should include the actual index at which the item(s) should be placed, for example array[2] will cause the value(s) to be the 3rd item(s) in the array.

The array must already exist and the LCB_SDSPEC_F_MKINTERMEDIATES flag is not honored.


Increment or decrement an existing numeric path.

If the number does not exist, it will be created (though its parents will not, unless LCB_SDSPEC_F_MKINTERMEDIATES is specified).

The value for this operation should be a valid JSON-encoded integer and must be between INT64_MIN and INT64_MAX, inclusive.


Remove an existing path in the document.


Count the number of elements in an array or dictionary.


Retrieve the entire document.


Replace the entire document.


Remove the entire document.