Subdocument

Enumerations

enum couchbase.subdocument.StoreSemantics(value)

Define subdocument mutation operation store semantics.

Member Type:

int

Valid values are as follows:

REPLACE = <StoreSemantics.REPLACE: 0>
UPSERT = <StoreSemantics.UPSERT: 1>
INSERT = <StoreSemantics.INSERT: 2>

Lookup Operations

couchbase.subdocument.count(path, xattr=False) → Spec

Creates a Spec that returns the number of elements in the array referenced by the path.

Parameters:

  • path (str) – The path to the field.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.exists(path, xattr=False) → Spec

Creates a Spec that returns whether a specific field exists in the document.

Parameters:

  • path (str) – The path to the field.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.get(path, xattr=False) → Spec

Creates a Spec for retrieving an element’s value given a path.

Parameters:

  • path (str) – The path to the field.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

Mutation Operations

couchbase.subdocument.array_addunique(path, value, create_parents=False, xattr=False) → Spec

Creates a Spec for adding unique values to an array in a document. This operation will only add values if they do not already exist elsewhere in the array.

Parameters:

  • path (str) – The path to an element of an array.

  • value (Union[str, int, float, bool, None]) – The value to add into the array.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.array_append(path, *values, create_parents=False, xattr=False) → Spec

Creates a Spec for adding a value to the end of an array in a document.

Parameters:

  • path (str) – The path to an element of an array.

  • *values (Iterable[Any]) – The values to add.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.array_insert(path, *values, create_parents=False, xattr=False) → Spec

Creates a Spec for adding a value to a specified location in an array in a document. The path should specify a specific index in the array and the new values are inserted at this location.

Parameters:

  • path (str) – The path to an element of an array.

  • *values (Iterable[Any]) – The values to add.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.array_prepend(path, *values, create_parents=False, xattr=False) → Spec

Creates a Spec for adding a value to the beginning of an array in a document.

Parameters:

  • path (str) – The path to an element of an array.

  • *values (Iterable[Any]) – The values to add.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.counter(path, delta, xattr=False, create_parents=False) → Spec

Creates a Spec for incrementing or decrementing the value of a field in a document. If the provided delta is >= 0 increment() is called, otherwise decrement() is called.

Warning

This method is deprecated use increment() or decrement()

Parameters:

  • path (str) – The path to the field.

  • delta (int) – The value to increment or decrement from the document.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.decrement(path, delta, xattr=False, create_parents=False) → Spec

Creates a Spec for decrementing the value of a field in a document.

Parameters:

  • path (str) – The path to the field.

  • delta (int) – The value to decrement from the document.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

Returns:

An instance of Spec.

Return type:

Spec

Raises:

InvalidArgumentException – If the delta arugment is not >= 0 or not of type int.

couchbase.subdocument.increment(path, delta, xattr=False, create_parents=False) → Spec

Creates a Spec for incrementing the value of a field in a document.

Parameters:

  • path (str) – The path to the field.

  • delta (int) – The value to increment from the document.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

Returns:

An instance of Spec.

Return type:

Spec

Raises:

InvalidArgumentException – If the delta arugment is not >= 0 or not of type int.

couchbase.subdocument.remove(path, xattr=False) → Spec

Creates a Spec for removing a field from a document.

Parameters:

  • path (str) – The path to the field.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.replace(path, value, xattr=False) → Spec

Creates a Spec for replacing a field into the document. Failing if the field already exists at the specified path.

Parameters:

  • path (str) – The path to the field.

  • value (Union[JSONType, MutationMacro]) – The value to write.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

couchbase.subdocument.upsert(path, value, create_parents=False, xattr=False) → Spec

Creates a Spec for upserting a field into the document. This updates the value of the specified field, or creates the field if it does not exits.

Parameters:

  • path (str) – The path to the field.

  • value (Union[JSONType, MutationMacro]) – The value to upsert.

  • create_parents (bool, optional) – Whether or not the path to the field should be created if it does not already exist.

  • xattr (bool, optional) – Whether this operation should reference the document body or the extended attributes data for the document.

Returns:

An instance of Spec.

Return type:

Spec

Options

class couchbase.options.LookupInOptions(timeout=None, access_deleted=None)

Available options to for a subdocument lookup-in operation.

Warning

Importing options from couchbase.collection is deprecated. All options should be imported from couchbase.options.

Parameters:

timeout (timedelta, optional) – The timeout for this operation. Defaults to global subdocument operation timeout.

class couchbase.options.MutateInOptions(timeout=None, cas=0, durability=None, store_semantics=None, access_deleted=None, preserve_expiry=None)

Available options to for a subdocument mutate-in operation.

Warning

Importing options from couchbase.subdocument is deprecated. All options should be imported from couchbase.options.

Parameters:

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to global subdocument operation timeout.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved.

  • store_semantics (StoreSemantics, optional) – Specifies the store semantics to use for this operation.

Results

class couchbase.result.LookupInResult
property cas: int | None

The CAS of the document, if it exists

Type:

Optional[int]

property content_as: ContentSubdocProxy

A proxy to return the value at the specified index.

Get first value as a dict:

res = collection.lookup_in(key, (SD.get("geo"), SD.exists("city")))
value = res.content_as[dict](0)
Type:

ContentSubdocProxy

class couchbase.result.MutateInResult
property cas: int | None

The CAS of the document, if it exists

Type:

Optional[int]