Sub-document operations
Specs
|
One operation of a |
|
What |
|
The sub-document status codes of the memcached protocol. |
- class couchbase.subdocument.Spec(*args: Any, **kwargs: Any)
One operation of a
lookup_inormutate_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_indoes 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
Paths to the virtual attributes the server keeps on every document, for |
|
|
Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
- class couchbase.subdocument.LookupInMacro
Paths to the virtual attributes the server keeps on every document, for
lookup_in.Each is read with
xattr=True.
- couchbase.subdocument.count(path: str, xattr: bool | None = False) Spec
Creates a
Specthat returns the number of elements in the array referenced by the path.
- couchbase.subdocument.exists(path: str, xattr: bool | None = False) Spec
Creates a
Specthat returns whether a specific field exists in the document.
Mutations
|
A value the server fills in from the mutation that writes it. |
|
Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
The CAS a |
|
|
DEPRECATED Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
|
Creates a |
Creates a |
- 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.
- 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
Specthat adds a value to an array unless the array already holds it.A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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:
- 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
Specthat adds values to the end of an array.A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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:
- 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
Specthat adds values at a position in an array.The path ends in the index to insert at, as in
tags[2]. AMutationMacrovalue is written to the extended attributes, whateverxattrsays, 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:
- 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
Specthat adds values to the start of an array.A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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:
- 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.
- couchbase.subdocument.counter(path: str, delta: int, xattr: bool | None = False, create_parents: bool | None = False) Spec
DEPRECATED Creates a
Specthat adds a delta to a number.A positive delta calls
increment(), and a negative onedecrement().Deprecated since version 4.0.0: Use
increment()ordecrement()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:
- 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
Specthat 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:
- 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
Specthat 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:
- 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
Specthat adds a field, failing if the field already exists.A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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. AMutationMacrovalue sets it.
- Returns:
The operation, for
mutate_in.- Return type:
- couchbase.subdocument.remove(path: str, xattr: bool | None = False) Spec
Creates a
Specthat removes a field.An empty path removes the whole document.
- couchbase.subdocument.replace(path: str, value: str | int | float | bool | None | Mapping[str, Any] | Sequence[Any] | MutationMacro, xattr: bool | None = False) Spec
Creates a
Specthat sets a field, failing if the field does not exist.An empty path replaces the whole body. A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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:
- 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
Specthat sets a field, adding it if it does not exist.A
MutationMacrovalue is written to the extended attributes, whateverxattrsays, 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: