Couchbase C Client  2.10.0
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

Functions

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...
 

Macros

#define LCB_SDSPEC_F_MKINTERMEDIATES
 Create intermediate paths.
 
#define LCB_SDSPEC_F_XATTRPATH
 Access document XATTR path.
 
#define LCB_SDSPEC_F_XATTR_MACROVALUES
 Access document virtual/materialized path. More...
 
#define LCB_SDSPEC_F_XATTR_DELETED_OK
 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_)
 
#define LCB_SDMULTI_MODE_INVALID
 
#define LCB_SDMULTI_MODE_LOOKUP
 
#define LCB_SDMULTI_MODE_MUTATE
 
#define LCB_CMDSUBDOC_F_UPSERT_DOC
 This command flag should be used if the document is to be created if it does not exist.
 
#define LCB_CMDSUBDOC_F_INSERT_DOC
 This command flag should be used if the document must be created anew. More...
 
#define LCB_CMDSUBDOC_F_ACCESS_DELETED
 Access a potentially deleted document. More...
 

Enumerations

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.

Warning
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.
Parameters
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.
Returns
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.
Examples:
example/subdoc/subdoc-xattrs.c.

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.

Examples:
example/subdoc/subdoc-xattrs.c.
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())

◆ lcb_RESPSUBDOC

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()

Examples:
example/subdoc/subdoc-xattrs.c.
Data Fields
LCB_RESP_BASE const void * responses
void * bufh Use with lcb_backbuf_ref/unref.

◆ lcb_SDENTRY

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

Examples:
example/subdoc/subdoc-xattrs.c.
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

◆ LCB_SDSPEC_F_XATTR_MACROVALUES

#define LCB_SDSPEC_F_XATTR_MACROVALUES

Access document virtual/materialized path.

Implies F_XATTRPATH

◆ LCB_SDSPEC_SET_PATH

#define LCB_SDSPEC_SET_PATH (   s,
  p,
 
)

Set the path for an lcb_SDSPEC structure.

Parameters
spointer to spec
pthe path buffer
nthe length of the path buffer
Examples:
example/subdoc/subdoc-xattrs.c.

◆ LCB_SDSPEC_SET_VALUE

#define LCB_SDSPEC_SET_VALUE (   s,
  v,
 
)

Set the value for the lcb_SDSPEC structure.

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

◆ LCB_CMDSUBDOC_F_INSERT_DOC

#define LCB_CMDSUBDOC_F_INSERT_DOC

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

In this case, it will fail if it already exists

◆ LCB_CMDSUBDOC_F_ACCESS_DELETED

#define LCB_CMDSUBDOC_F_ACCESS_DELETED

Access a potentially deleted document.

For internal Couchbase use

Enumeration Type Documentation

◆ lcb_SUBDOCOP

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.

Enumerator
LCB_SDCMD_GET 

Retrieve the value for a path.

LCB_SDCMD_EXISTS 

Check if the value for a path exists.

If the path exists then the error code will be LCB_SUCCESS

LCB_SDCMD_REPLACE 

Replace the value at the specified path.

This operation can work on any existing and valid path.

LCB_SDCMD_DICT_ADD 

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.

LCB_SDCMD_DICT_UPSERT 

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.

LCB_SDCMD_ARRAY_ADD_FIRST 

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).

LCB_SDCMD_ARRAY_ADD_LAST 

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

LCB_SDCMD_ARRAY_ADD_UNIQUE 

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).

LCB_SDCMD_ARRAY_INSERT 

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.

LCB_SDCMD_COUNTER 

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.

LCB_SDCMD_REMOVE 

Remove an existing path in the document.

LCB_SDCMD_GET_COUNT 

Count the number of elements in an array or dictionary.

LCB_SDCMD_GET_FULLDOC 

Retrieve the entire document.

LCB_SDCMD_SET_FULLDOC 

Replace the entire document.

LCB_SDCMD_REMOVE_FULLDOC 

Remove the entire document.