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.subdoc 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 – operation is done on an Extended Attribute.

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.

Returns

Spec

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

Gets the count of a list or dictionary element given a path

Parameters
  • path – String path - path to the element

  • xattr (bool) – operation is done on an Extended Attribute.

Returns

Spec

couchbase.subdocument.get_full()[source]

Fetches the entire document.

Returns

Spec

Mutation Operations

couchbase.subdocument.upsert(path, value, create_parents=False, **kwargs)[source]

Create or replace a dictionary path.

Parameters
  • path – The path to modify

  • value – The new value for the path. This should be a native Python object which can be encoded into JSON (the SDK will do the encoding for you).

  • create_parents

    Whether intermediate parents should be created. This means creating any additional levels of hierarchy not already in the document, for example:

    {'foo': {}}
    

    Without create_parents, an operation such as

    cb.mutate_in("docid", SD.upsert("foo.bar.baz", "newValue"))
    

    would fail with couchbase_core.exceptions.SubdocPathNotFoundError because foo.bar does not exist. However when using the create_parents option, the server creates the new foo.bar dictionary and then inserts the baz value.

couchbase.subdocument.replace(path, value, **kwargs)[source]

Replace an existing path. This works on any valid path if the path already exists. Valid only in mutate_in()

Parameters
  • path – The path to replace

  • value – The new value

couchbase.subdocument.insert(path, value, create_parents=False, **kwargs)[source]

Create a new path in the document. The final path element points to a dictionary key that should be created. Valid only in mutate_in()

Parameters
  • path – The path to create

  • value – Value for the path

  • create_parents – Whether intermediate parents should be created

couchbase.subdocument.array_append(path, *values, **kwargs)[source]

Add new values to the end of an array.

Parameters
  • path – Path to the array. The path should contain the array itself and not an element within the array

  • values – one or more values to append

  • create_parents – Create the array if it does not exist

Note

Specifying multiple values in values is more than just syntactical sugar. It allows the server to insert the values as one single unit. If you have multiple values to append to the same array, ensure they are specified as multiple arguments to array_append rather than multiple array_append commands to mutate_in()

This operation is only valid in mutate_in().

couchbase.subdocument.array_prepend(path, *values, **kwargs)[source]

Add new values to the beginning of an array.

Parameters
  • path – Path to the array. The path should contain the array itself and not an element within the array

  • values – one or more values to append

  • create_parents – Create the array if it does not exist

This operation is only valid in mutate_in().

couchbase.subdocument.array_insert(path, *values, **kwargs)[source]

Insert items at a given position within an array.

Parameters
  • path – The path indicating where the item should be placed. The path _should_ contain the desired position

  • values – Values to insert

This operation is only valid in mutate_in().

couchbase.subdocument.array_addunique(path, value, create_parents=False, **kwargs)[source]

Add a new value to an array if the value does not exist.

Parameters
  • path – The path to the array

  • value – Value to add to the array if it does not exist. Currently the value is restricted to primitives: strings, numbers, booleans, and None values.

  • create_parents – Create the array if it does not exist

Note

The actual position of the new item is unspecified. This means it may be at the beginning, end, or middle of the existing array)

This operation is only valid in mutate_in().

couchbase.subdocument.remove(path, **kwargs)[source]

Remove an existing path in the document.

This operation is only valid in mutate_in().

Parameters

path – The path to remove

couchbase.subdocument.counter(path, delta, create_parents=False, **kwargs)[source]

Increment or decrement a counter in a document.

Parameters
  • path – Path to the counter

  • delta – Amount by which to modify the value. The delta can be negative but not 0. It must be an integer (not a float) as well.

  • create_parents – Create the counter (and apply the modification) if it does not exist

Note

Unlike couchbase_core.client.Client.counter(), there is no initial argument. If the counter does not exist within the document (but its parent does, or create_parents is true), it will be initialized with the value of the delta.

This operation is only valid in mutate_in().

See also

upsert(), counter() (in Client)

Result Object

class couchbase.result.LookupInResult(content, *args, **kwargs)[source]

LookupInResult is the return type for lookup_in operations. Constructed internally by the API.

class couchbase.result.MutateInResult(content, **options)[source]

MutateInResult is the return type for mutate_in operations. Constructed internally by the API.

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