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

couchbase.subdocument.count(path, xattr=False)[source]

Gets the count of a list or dictionary element 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

couchbase.subdocument.get_full()[source]

Fetches the entire document.

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 path

  • kwargs (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 path

  • kwargs (Any) – Specify create_parents=True to create the array.

Return type

Spec

Returns

couchbase.subdocument.array_insert(path, *values, xattr=False)[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.

  • values (Union[str, int, float, bool, None, Mapping[str, ForwardRef], List[ForwardRef]]) – Value(s) to insert.

  • xattr (bool) – whether this is an xattr path

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 path

  • create_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 path

  • create_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: couchbase.result.ContentProxySubdoc

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

ContentProxySubdoc

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: couchbase.result.ContentProxySubdoc

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

ContentProxySubdoc

Returns

returns a ContentProxySubdoc

property key: str

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