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:
- binary() BinaryCollection
Get the binary operations on this collection.
See also
- Returns:
A BinaryCollection instance.
- Return type:
- 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
GetReplicaResultrepresenting 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:
key (str) – The key for the document to retrieve.
strategy (
GetReplicaStrategy) – Selects the replica to read, created byfrom_index().opts (
GetReplicaOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
GetReplicaOptions
- Returns:
An instance of
GetReplicaResult.- Return type:
Deferred[
GetReplicaResult]- Raises:
DocumentNotFoundOnReplicaException – If the replica does not hold the document.
ReplicaIndexOutOfBoundsException – If the bucket has no replica at the requested index, and the strategy does not wrap.
ReplicaIndexCurrentlyUnavailableException – If the requested replica cannot be read now, and the strategy does not wrap or no other replica can be read either.
InvalidArgumentException – If
strategywas not created byfrom_index().
- 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
LookupInReplicaResultrepresenting 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.
- 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:
DocumentNotFoundException – If the key provided does not exist on the server.
DocumentLockedException – If the provided cas is invalid.
- 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