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.subdocument. This is done via

import couchbase.subdocument as SD

Lookup Operations

Mutation Operations

Result Object

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