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

Warning

The sub-document API is experimental and subject to change and is here for demonstration purposes only.

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

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

Function Documentation

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

	resp	the response received from within the callback.
[out]	out	structure to store the current result
[in,out]	iter	internal 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.

---

Data Structure Documentation

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

#define LCB_SDSPEC_SET_PATH	(		s,
			p,
			n
	)

Set the path for an lcb_SDSPEC structure.

Parameters

s	pointer to spec
p	the path buffer
n	the length of the path buffer

#define LCB_SDSPEC_SET_VALUE	(		s,
			v,
			n
	)

Set the value for the lcb_SDSPEC structure.

Parameters

s	pointer to spec
v	the value buffer
n	the length of the value buffer

Enumeration Type Documentation

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