Sub-document operations

Specs

Spec(*args, **kwargs)

One operation of a lookup_in or mutate_in, as the functions in this module create it.

StoreSemantics(value[, names, module, ...])

What mutate_in does about the document itself.

SubDocStatus(value[, names, module, ...])

The sub-document status codes of the memcached protocol.

class couchbase.subdocument.Spec(*args: Any, **kwargs: Any)

One operation of a lookup_in or mutate_in, as the functions in this module create it.

class couchbase.subdocument.StoreSemantics(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

What mutate_in does about the document itself.

REPLACE requires the document to exist, UPSERT creates it if it does not, and INSERT requires that it does not.

INSERT = 2
REPLACE = 0
UPSERT = 1
class couchbase.subdocument.SubDocStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The sub-document status codes of the memcached protocol.

CanOnlyReviveDeletedDocuments = 214
DeltaInvalid = 200
DocNotJson = 198
NumRangeError = 199
PathExists = 201
PathInvalid = 194
PathMismatch = 193
PathNotFound = 192
PathTooBig = 195
TooDeep = 196
ValueCannotInsert = 197
ValueTooDeep = 202
XattrCannotModifyVattr = 210
XattrInvalidFlagCombo = 206
XattrInvalidKeyCombo = 207
XattrUnknownMacro = 208
XattrUnknownVattr = 209
XattrUnknownVattrMacro = 213

Lookups

LookupInMacro()

Paths to the virtual attributes the server keeps on every document, for lookup_in.

count(path[, xattr])

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

exists(path[, xattr])

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

get(path[, xattr])

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

get_full()

Creates a Spec that reads the whole body.

class couchbase.subdocument.LookupInMacro

Paths to the virtual attributes the server keeps on every document, for lookup_in.

Each is read with xattr=True.

static cas() → str

The path to the document’s CAS, as a hex string.

static document() → str

The path to all of the document’s metadata, as one object.

static expiry_time() → str

The path to the document’s expiry time, in seconds since the epoch, 0 if it has none.

static is_deleted() → str

The path to whether the document is a tombstone.

static last_modified() → str

The path to when the document last changed, in seconds since the epoch.

static rev_id() → str

The path to the document’s revision ID.

static seq_no() → str

The path to the document’s sequence number, as a hex string.

static value_size_bytes() → str

The path to the size of the document’s body, in bytes.

couchbase.subdocument.count(path: str, xattr: bool | None = 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: str, xattr: bool | None = 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: str, xattr: bool | None = 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

couchbase.subdocument.get_full() → Spec

Creates a Spec that reads the whole body.

Returns:

The operation, for lookup_in.

Return type:

Spec

Mutations

MutationMacro(value)

A value the server fills in from the mutation that writes it.

array_addunique(path, value[, ...])

Creates a Spec that adds a value to an array unless the array already holds it.

array_append(path, *values[, ...])

Creates a Spec that adds values to the end of an array.

array_insert(path, *values[, ...])

Creates a Spec that adds values at a position in an array.

array_prepend(path, *values[, ...])

Creates a Spec that adds values to the start of an array.

convert_macro_cas_to_cas(cas)

The CAS a MutationMacro.cas() field holds, as the int a result reports.

counter(path, delta[, xattr, create_parents])

DEPRECATED Creates a Spec that adds a delta to a number.

decrement(path, delta[, xattr, create_parents])

Creates a Spec that subtracts from a number.

increment(path, delta[, xattr, create_parents])

Creates a Spec that adds to a number.

insert(path, value[, create_parents, xattr])

Creates a Spec that adds a field, failing if the field already exists.

remove(path[, xattr])

Creates a Spec that removes a field.

replace(path, value[, xattr])

Creates a Spec that sets a field, failing if the field does not exist.

upsert(path, value[, create_parents, xattr])

Creates a Spec that sets a field, adding it if it does not exist.

with_expiry()

Creates a Spec that reads the document's expiry time.

class couchbase.subdocument.MutationMacro(value: str)

A value the server fills in from the mutation that writes it.

Parameters:

value (str) – The macro, as the server names it. The class methods return the ones it knows.

classmethod cas() → MutationMacro

The mutation’s CAS.

The server writes it as a hex string in little-endian byte order; convert_macro_cas_to_cas() reads it back as the CAS a result reports.

classmethod seq_no() → MutationMacro

The mutation’s sequence number, as a hex string.

property value: str

The macro, as the server names it.

classmethod value_crc32c() → MutationMacro

The CRC32C checksum of the document’s body after the mutation, as a hex string.

couchbase.subdocument.array_addunique(path: str, value: str | int | float | bool | MutationMacro | None, create_parents: bool | None = False, xattr: bool | None = False) → Spec

Creates a Spec that adds a value to an array unless the array already holds it.

A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

Parameters:
  • path (str) – The path to the array.

  • value (str | int | float | bool | MutationMacro | None) – The value to add.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.array_append(path: str, *values: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, create_parents: bool | None = False, xattr: bool | None = False) → Spec

Creates a Spec that adds values to the end of an array.

A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

Parameters:
  • path (str) – The path to the array.

  • *values (JSONType | MutationMacro) – The values to add, in order.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.array_insert(path: str, *values: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, create_parents: bool | None = False, xattr: bool | None = False) → Spec

Creates a Spec that adds values at a position in an array.

The path ends in the index to insert at, as in tags[2]. A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

Parameters:
  • path (str) – The path to the array, ending in the index.

  • *values (JSONType | MutationMacro) – The values to add, in order.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.array_prepend(path: str, *values: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, create_parents: bool | None = False, xattr: bool | None = False) → Spec

Creates a Spec that adds values to the start of an array.

A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

Parameters:
  • path (str) – The path to the array.

  • *values (JSONType | MutationMacro) – The values to add, in order.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.convert_macro_cas_to_cas(cas: str) → int

The CAS a MutationMacro.cas() field holds, as the int a result reports.

The server writes that macro as a hex string in little-endian byte order, so its bytes are reversed before they are read.

Parameters:

cas (str) – The field’s value, with or without a 0x prefix.

Returns:

The CAS.

Return type:

int

couchbase.subdocument.counter(path: str, delta: int, xattr: bool | None = False, create_parents: bool | None = False) → Spec

DEPRECATED Creates a Spec that adds a delta to a number.

A positive delta calls increment(), and a negative one decrement().

Deprecated since version 4.0.0: Use increment() or decrement() instead.

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

  • delta (int) – The amount to add. Must not be 0.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

Raises:

InvalidArgumentException – If the delta is 0 or not an int.

couchbase.subdocument.decrement(path: str, delta: int, xattr: bool | None = False, create_parents: bool | None = False) → Spec

Creates a Spec that subtracts from a number.

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

  • delta (int) – The amount to subtract. Must be greater than 0.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

Raises:

InvalidArgumentException – If the delta is not an int greater than 0.

couchbase.subdocument.increment(path: str, delta: int, xattr: bool | None = False, create_parents: bool | None = False) → Spec

Creates a Spec that adds to a number.

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

  • delta (int) – The amount to add. Must be greater than 0.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

Raises:

InvalidArgumentException – If the delta is not an int greater than 0.

couchbase.subdocument.insert(path: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, create_parents: bool | None = False, xattr: bool | None = False, **kwargs: Any) → Spec

Creates a Spec that adds a field, failing if the field already exists.

A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

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

  • value (JSONType | MutationMacro) – The value to add.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

  • **kwargs – expand_macros (bool) asks the server to expand macros in a str value. A MutationMacro value sets it.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.remove(path: str, xattr: bool | None = False) → Spec

Creates a Spec that removes a field.

An empty path removes the whole document.

Parameters:
  • path (str) – The path to the field, or an empty str for the whole document.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.replace(path: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, xattr: bool | None = False) → Spec

Creates a Spec that sets a field, failing if the field does not exist.

An empty path replaces the whole body. A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

Parameters:
  • path (str) – The path to the field, or an empty str for the whole body.

  • value (JSONType | MutationMacro) – The value to set.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.upsert(path: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, create_parents: bool | None = False, xattr: bool | None = False) → Spec

Creates a Spec that sets a field, adding it if it does not exist.

A MutationMacro value is written to the extended attributes, whatever xattr says, with the macro expanded by the server.

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

  • value (JSONType | MutationMacro) – The value to set.

  • create_parents (bool, optional) – Whether to create the path’s missing parent fields. Defaults to False.

  • xattr (bool, optional) – Whether the path is in the document’s extended attributes rather than its body. Defaults to False.

Returns:

The operation, for mutate_in.

Return type:

Spec

couchbase.subdocument.with_expiry() → Spec

Creates a Spec that reads the document’s expiry time.

Returns:

The operation, for lookup_in.

Return type:

Spec