Collection

class txcouchbase.collection.Collection(scope: Scope, name: str)

A collection in a scope, and the key-value operations on its documents.

Get one from collection().

Parameters:
  • scope (Scope) – The scope the collection belongs to.

  • name (str) – The name of the collection.

binary() → BinaryCollection

Get the binary operations on this collection.

See also

BinaryCollection

Returns:

A BinaryCollection instance.

Return type:

BinaryCollection

static default_name() → str

The name of a bucket’s default collection.

exists(key: str, opts: ExistsOptions | None = None, **kwargs: Unpack[ExistsOptionsKwargs]) → Deferred[ExistsResult]

Checks whether a specific document exists or not.

Parameters:
  • key (str) – The key for the document to check existence.

  • opts (ExistsOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided ExistsOptions

Returns:

An instance of ExistsResult.

Return type:

Deferred[ExistsResult]

get(key: str, opts: GetOptions | None = None, **kwargs: Unpack[GetOptionsKwargs]) → Deferred[GetResult]

Retrieves the value of a document from the collection.

Parameters:
  • key (str) – The key for the document to retrieve.

  • opts (GetOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided GetOptions

Returns:

An instance of GetResult.

Return type:

Deferred[GetResult]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

get_all_replicas(key: str, opts: GetAllReplicasOptions | None = None, **kwargs: Unpack[GetAllReplicasOptionsKwargs]) → Deferred[Iterable[GetReplicaResult]]

Retrieves the value of a document from the collection returning both active and all available replicas.

Parameters:
  • key (str) – The key for the document to retrieve.

  • opts (GetAllReplicasOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided GetAllReplicasOptions

Returns:

A stream of GetReplicaResult representing both active and replicas of the document retrieved.

Return type:

Deferred[Iterable[GetReplicaResult]]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

get_and_lock(key: str, lock_time: timedelta, opts: GetAndLockOptions | None = None, **kwargs: Unpack[GetAndLockOptionsKwargs]) → Deferred[GetResult]

Locks a document and retrieves the value of that document at the time it is locked.

Parameters:
  • key (str) – The key for the document to lock and retrieve.

  • lock_time (timedelta) – The amount of time to lock the document.

  • opts (GetAndLockOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided GetAndLockOptions

Returns:

An instance of GetResult.

Return type:

Deferred[GetResult]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

get_and_touch(key: str, expiry: timedelta, opts: GetAndTouchOptions | None = None, **kwargs: Unpack[GetAndTouchOptionsKwargs]) → Deferred[GetResult]

Retrieves the value of the document and simultanously updates the expiry time for the same document.

Parameters:
  • key (str) – The key for the document retrieve and set expiry time.

  • expiry (timedelta) – The new expiry to apply to the document.

  • opts (GetAndTouchOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided GetAndTouchOptions

Returns:

An instance of GetResult.

Return type:

Deferred[GetResult]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

get_any_replica(key: str, opts: GetAnyReplicaOptions | None = None, **kwargs: Unpack[GetAnyReplicaOptionsKwargs]) → Deferred[GetReplicaResult]

Retrieves a document from whichever of the active copy and the replicas answers first.

Parameters:
  • key (str) – The key for the document to retrieve.

  • opts (GetAnyReplicaOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided GetAnyReplicaOptions

Returns:

An instance of GetReplicaResult.

Return type:

Deferred[GetReplicaResult]

Raises:

DocumentUnretrievableException – If the key provided does not exist on the server.

get_replica(key: str, strategy: GetReplicaStrategy, opts: GetReplicaOptions | None = None, **kwargs: Unpack[GetReplicaOptionsKwargs]) → Deferred[GetReplicaResult]

Retrieves a document from the replica the strategy selects.

Parameters:
Returns:

An instance of GetReplicaResult.

Return type:

Deferred[GetReplicaResult]

Raises:
insert(key: str, value: Any, opts: InsertOptions | None = None, **kwargs: Unpack[InsertOptionsKwargs]) → Deferred[MutationResult]

Inserts a new document to the collection, failing if the document already exists.

Parameters:
  • key (str) – Document key to insert.

  • value (DocumentValue) – The value of the document to insert.

  • opts (InsertOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided InsertOptions

Returns:

An instance of MutationResult.

Return type:

Deferred[MutationResult]

Raises:

DocumentExistsException – If the document already exists on the server.

lookup_in(key: str, spec: Iterable[Spec], opts: LookupInOptions | None = None, **kwargs: Unpack[LookupInOptionsKwargs]) → Deferred[LookupInResult]

Fetches individual fields of a document, or information about them.

Parameters:
  • key (str) – The key for the document look in.

  • spec (Iterable[Spec]) – A list of specs describing the data to fetch from the document.

  • opts (LookupInOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided LookupInOptions

Returns:

An instance of LookupInResult.

Return type:

Deferred[LookupInResult]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

lookup_in_all_replicas(key: str, spec: Iterable[Spec], opts: LookupInAllReplicasOptions | None = None, **kwargs: Unpack[LookupInAllReplicasOptionsKwargs]) → Deferred[Iterable[LookupInReplicaResult]]

Fetches fields of a document from the active copy and every available replica.

Parameters:
  • key (str) – The key for the document look in.

  • spec (Iterable[Spec]) – A list of specs describing the data to fetch from the document.

  • opts (LookupInAllReplicasOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided LookupInAllReplicasOptions

Returns:

A stream of LookupInReplicaResult representing both active and replicas of the sub-document retrieved.

Return type:

Deferred[Iterable[LookupInReplicaResult]]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

lookup_in_any_replica(key: str, spec: Iterable[Spec], opts: LookupInAnyReplicaOptions | None = None, **kwargs: Unpack[LookupInAnyReplicaOptionsKwargs]) → Deferred[LookupInReplicaResult]

Fetches fields of a document from whichever of the active copy and the replicas answers first.

Parameters:
  • key (str) – The key for the document look in.

  • spec (Iterable[Spec]) – A list of specs describing the data to fetch from the document.

  • opts (LookupInAnyReplicaOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided LookupInAnyReplicaOptions

Returns:

An instance of LookupInReplicaResult.

Return type:

Deferred[LookupInReplicaResult]

Raises:

DocumentUnretrievableException – If the key provided does not exist on the server.

mutate_in(key: str, spec: Iterable[Spec], opts: MutateInOptions | None = None, **kwargs: Unpack[MutateInOptionsKwargs]) → Deferred[MutateInResult]

Atomically modifies individual fields of a document.

The fields may include the document’s extended attributes (xattrs).

Parameters:
  • key (str) – The key for the document look in.

  • spec (Iterable[Spec]) – A list of specs describing the operations to perform on the document.

  • opts (MutateInOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided MutateInOptions

Returns:

An instance of MutateInResult.

Return type:

Deferred[MutateInResult]

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

property name: str

The name of this collection.

remove(key: str, opts: RemoveOptions | None = None, **kwargs: Unpack[RemoveOptionsKwargs]) → Deferred[MutationResult]

Removes an existing document. Failing if the document does not exist.

Parameters:
  • key (str) – Key for the document to remove.

  • opts (RemoveOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided RemoveOptions

Returns:

An instance of MutationResult.

Return type:

Deferred[MutationResult]

Raises:

DocumentNotFoundException – If the document does not exist on the server.

replace(key: str, value: Any, opts: ReplaceOptions | None = None, **kwargs: Unpack[ReplaceOptionsKwargs]) → Deferred[MutationResult]

Replaces the value of an existing document. Failing if the document does not exist.

Parameters:
  • key (str) – Document key to replace.

  • value (DocumentValue) – The value of the document to replace.

  • opts (ReplaceOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided ReplaceOptions

Returns:

An instance of MutationResult.

Return type:

Deferred[MutationResult]

Raises:

DocumentNotFoundException – If the document does not exist on the server.

touch(key: str, expiry: timedelta, opts: TouchOptions | None = None, **kwargs: Unpack[TouchOptionsKwargs]) → Deferred[MutationResult]

Updates the expiry on an existing document.

Parameters:
  • key (str) – Key for the document to touch.

  • expiry (timedelta) – The new expiry for the document.

  • opts (TouchOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided TouchOptions

Returns:

An instance of MutationResult.

Return type:

Deferred[MutationResult]

Raises:

DocumentNotFoundException – If the document does not exist on the server.

unlock(key: str, cas: int, opts: UnlockOptions | None = None, **kwargs: Unpack[UnlockOptionsKwargs]) → Deferred[None]

Unlocks a previously locked document.

Parameters:
  • key (str) – The key for the document to unlock.

  • cas (int) – The CAS of the document, used to validate lock ownership.

  • opts (UnlockOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided UnlockOptions

Raises:
upsert(key: str, value: Any, opts: UpsertOptions | None = None, **kwargs: Unpack[UpsertOptionsKwargs]) → Deferred[MutationResult]

Upserts a document to the collection. This operation succeeds whether or not the document already exists.

Parameters:
  • key (str) – Document key to upsert.

  • value (DocumentValue) – The value of the document to upsert.

  • opts (UpsertOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used in place or to override provided UpsertOptions

Returns:

An instance of MutationResult.

Return type:

Deferred[MutationResult]

txcouchbase.collection.TxCollection

alias of Collection