Sub-Document API¶
The functions in this module can be used to specify operations to the
lookup_in()
and mutate_in()
methods. Both the
mutate_in and lookup_in methods can take multiple operations.
Any given operation is either valid in lookup_in()
or
mutate_in()
; never both.
Internally every function in this module returns an object specifying the path, options, and value of the command, so for example:
cb.mutate_in(key,
(SD.upsert('path1', 'value1'),
SD.insert('path2', 'value2', create_parents=True)))
really becomes
cb.mutate_in(key,
(CMD_SUBDOC_UPSERT, 'path1', 'value1', 0),
(CMD_SUBDOC_INSERT, 'path2', 'value2', 1))
Thus, the actual operations are performed when the mutate_in or lookup_in methods are executed, the functions in this module just acting as an interface to specify what sorts of operations are to be executed.
Throughout the SDK documentation, this module is referred to as SD
which
is significantly easier to type than couchbase_core.subdocument
. This is done
via
import couchbase.subdocument as SD
Lookup Operations¶
-
couchbase.subdocument.
exists
(path, xattr=False)[source]¶ Checks for the existence of a field given a path.
- Parameters
path (str) – path to the element
xattr (
bool
) – operation is done on an Extended Attribute.
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
get
(path, xattr=False)[source]¶ Fetches an element’s value given a path.
- Parameters
path (str) – String path - path to the element
xattr (bool) – operation is done on an Extended Attribute.
- Return type
Spec
- Returns
Spec
Mutation Operations¶
-
couchbase.subdocument.
upsert
(path, value, create_parents=False, xattr=False)[source]¶ Upsert a value into a document at a given path
- Parameters
path (str) – Path at which to upsert the value.
value (JSON) – Value to upsert.
create_parents (bool) – Whether or not to create parents if needed.
xattr (False) – whether this is an xattr path
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
replace
(path, value, xattr=False)[source]¶ Replace value at a path with the value given.
- Parameters
path (str) – Path at which to replace the value.
value (
Union
[str
,int
,float
,bool
,None
,Mapping
[str
,ForwardRef
],List
[ForwardRef
]]) – Value you would like at the path given.xattr (
bool
) – whether this is an xattr path
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
insert
(path, value, create_parents=False, xattr=False)[source]¶ Insert a value at a given path in a document.
- Parameters
path (str) – Path to insert into document.
value (JSON) – Value to insert at this path.
create_parents (bool) – Whether or not to create the parents in the path, if they don’t already exist.
xattr (False) – whether this is an xattr path
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
array_append
(path, *values, xattr=False, **kwargs)[source]¶ Append values to the end of an array in a document.
- Parameters
path (str) – Path to an array in document. Note this is the path to the array, not to the path to a specific element.
values (JSON) – Value(s) to append to the array.
xattr (
bool
) – whether this is an xattr pathkwargs (Any) – Specify create_parents=True to create the array.
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
array_prepend
(path, *values, xattr=False, **kwargs)[source]¶ Append values to the beginning of an array in a document.
- Parameters
path (str) – Path to an array in document. Note this is the path to the array, not to the path to a specific element.
values (JSON) – Value(s) to prepend to the array.
xattr (
bool
) – whether this is an xattr pathkwargs (Any) – Specify create_parents=True to create the array.
- Return type
Spec
- Returns
-
couchbase.subdocument.
array_insert
(path, xattr=False, *values)[source]¶ Insert values at into an array in a document at the position given in the path.
- Parameters
path (str) – Path to the spot in the array where the values should be inserted. Note in this case, the path is a path to a specific location in an array.
xattr (
bool
) – whether this is an xattr pathvalues (
Union
[str
,int
,float
,bool
,None
,Mapping
[str
,ForwardRef
],List
[ForwardRef
]]) – Value(s) to insert.
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
array_addunique
(path, value, xattr=False, create_parents=False)[source]¶ Add a value to an existing array, if it doesn’t currently exist in the array. Note the position is unspecified – it is up to the server to place it where it wants. :param str path: Path to an array in a document. Note this is the path to
the array, not to the path to a specific element.
- Parameters
value – Value to add, if it does not already exist in the array.
xattr (
bool
) – whether this is an xattr pathcreate_parents (bool) – If True, create the array if it does not already exist.
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
remove
(path, xattr=False)[source]¶ Remove a path from a document.
- Parameters
path (str) – Path to remove from document.
xattr (
bool
) – whether this is an xattr path
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
counter
(path, delta, xattr=False, create_parents=False)[source]¶ Increment or decrement a counter in a document.
- Parameters
path (str) – Path to the counter
delta (int) – Amount to change the counter. Cannot be 0, and must be and integer.
xattr (
bool
) – whether this is an xattr pathcreate_parents (bool) – Create the counter if it doesn’t exist. Will be initialized to the value of delta.
- Return type
Spec
- Returns
Spec
-
couchbase.subdocument.
exists
(path, xattr=False)[source] Checks for the existence of a field given a path.
- Parameters
path (str) – path to the element
xattr (
bool
) – operation is done on an Extended Attribute.
- Return type
Spec
- Returns
Spec
Result Object¶
-
class
couchbase.result.
LookupInResult
(original, **kwargs)[source]¶ LookupInResult is the return type for lookup_in operations.
- Warning
This is an internal API call.
Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.
-
property
content_as
¶ Return a proxy that allows extracting the content as a provided type.
Get first value as a string:
value = cb.get('key').content_as[str](0)
- Return type
- Returns
returns as ContentProxySubdoc
-
class
couchbase.result.
MutateInResult
(content, **options)[source]¶ MutateInResult is the return type for mutate_in operations.
- Warning
This is an internal API call.
Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.
-
property
content_as
¶ Return a proxy that allows extracting the content as a provided type.
Get first result as a string:
cb.mutate_in('user', SD.array_addunique('tags', 'dog'), SD.counter('updates', 1)).content_as[str](0)
- Return type
- Returns
returns a
ContentProxySubdoc
-
property
key
¶ Original key of the operation
- Return type
str
Path Syntax¶
The path syntax is hierarchical and follows that of N1QL. Use a dot (.) to separate between components. A backtick may be used to escape dots or other special characters. Considering the dictionary:
{
'dict': {
'nestedDict': {
'value': 123
},
'nestedArray': [1,2,3],
'literal.dot': 'Hello',
'literal[]brackets': 'World'
},
'array': [1,2,3],
'primitive': True
}
Accessing paths can be done as:
dict
dict.nestedDict
dict.nestedDict.value
dict.nestedArray
dict.nestedArray[0]
dict.nestedArray[-1]
(gets last element)dict.`literal.dot`
dict.`literal[]brackets`
array
primitive