Transactions

couchbase.transactions

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

How hard a multi-document read inside a transaction works to avoid read skew.

Read skew is seeing some documents from before another transaction committed and some from after. PRIORITISE_LATENCY makes a time-bounded effort to avoid it, PRIORITISE_READ_SKEW_DETECTION makes a greater effort at a cost in latency, and DISABLE_READ_SKEW_DETECTION makes none.

DISABLE_READ_SKEW_DETECTION = 'disable_read_skew_detection'
PRIORITISE_LATENCY = 'prioritise_latency'
PRIORITISE_READ_SKEW_DETECTION = 'prioritise_read_skew_detection'
class couchbase.transactions.TransactionGetMultiReplicasFromPreferredServerGroupMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How hard a multi-document read inside a transaction works to avoid read skew.

Read skew is seeing some documents from before another transaction committed and some from after. PRIORITISE_LATENCY makes a time-bounded effort to avoid it, PRIORITISE_READ_SKEW_DETECTION makes a greater effort at a cost in latency, and DISABLE_READ_SKEW_DETECTION makes none.

DISABLE_READ_SKEW_DETECTION = 'disable_read_skew_detection'
PRIORITISE_LATENCY = 'prioritise_latency'
PRIORITISE_READ_SKEW_DETECTION = 'prioritise_read_skew_detection'
class couchbase.transactions.TransactionGetMultiReplicasFromPreferredServerGroupResult(res: _GetMultiResultSource, transcoders: list[Transcoder | None], default_transcoder: Transcoder)

The documents a multi-document read from the preferred server group returned, in the order of its specs.

property content_as: TransactionMultiContentProxy

A proxy to return the document at the specified index.

Get the first document as a dict:

res = ctx.get_multi_replicas_from_preferred_server_group(specs)
value = res.content_as[dict](0)

Reading a document that does not exist raises DocumentNotFoundException.

exists(index: int) → bool

Check whether the document at an index exists.

Parameters:

index – The index of the document’s spec.

Returns:

True if the document exists.

Return type:

bool

Raises:

InvalidIndexException – If the index is out of range.

class couchbase.transactions.TransactionGetMultiReplicasFromPreferredServerGroupSpec(collection: Collection | AsyncCollection, id: str, transcoder: Transcoder | None = None)

One document for a multi-document read inside a transaction from the preferred server group’s replicas.

collection

The collection the document is in.

Type:

couchbase.collection.Collection | acouchbase.collection.AsyncCollection

id

The document’s ID.

Type:

str

transcoder

The transcoder to decode the document with, if not the transaction’s default.

Type:

couchbase.common.transcoder.Transcoder | None

class couchbase.transactions.TransactionGetMultiResult(res: _GetMultiResultSource, transcoders: list[Transcoder | None], default_transcoder: Transcoder)

The documents a multi-document read inside a transaction returned, in the order of its specs.

property content_as: TransactionMultiContentProxy

A proxy to return the document at the specified index.

Get the first document as a dict:

res = ctx.get_multi(specs)
value = res.content_as[dict](0)

Reading a document that does not exist raises DocumentNotFoundException.

exists(index: int) → bool

Check whether the document at an index exists.

Parameters:

index – The index of the document’s spec.

Returns:

True if the document exists.

Return type:

bool

Raises:

InvalidIndexException – If the index is out of range.

class couchbase.transactions.TransactionGetMultiSpec(collection: Collection | AsyncCollection, id: str, transcoder: Transcoder | None = None)

One document for a multi-document read inside a transaction.

collection

The collection the document is in.

Type:

couchbase.collection.Collection | acouchbase.collection.AsyncCollection

id

The document’s ID.

Type:

str

transcoder

The transcoder to decode the document with, if not the transaction’s default.

Type:

couchbase.common.transcoder.Transcoder | None

class couchbase.transactions.TransactionGetResult(res: _GetResultSource, transcoder: Transcoder)

A document read inside a transaction.

property cas: int

The CAS of the document.

property content_as: ContentProxy

The contents of the document.

Get the value as a dict:

res = ctx.get(collection, key)
value = res.content_as[dict]
property id: str

The document’s ID.

class couchbase.transactions.TransactionKeyspace(bucket: str | None = None, scope: str | None = None, collection: str | None = None, coll: Collection | AsyncCollection | None = None)

The bucket, scope and collection that transaction metadata is written to.

Parameters:
  • bucket (str) – The name of the bucket.

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

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

  • coll (Collection, optional) –

    When given, the three names are read from it and the other arguments are ignored.

    Deprecated since version 4.7.0: Use from_collection() instead.

Raises:

InvalidArgumentException – If a name is missing and no collection was given.

property bucket: str

The name of the bucket.

property collection: str

The name of the collection.

classmethod from_collection(coll: Collection | AsyncCollection) → TransactionKeyspace

Name the bucket, scope and collection that a collection belongs to.

Parameters:

coll (Collection) – The collection to name.

Returns:

TransactionKeyspace

property scope: str

The name of the scope.

class couchbase.transactions.TransactionQueryResults(res: bytes, serializer: Serializer | None = None)

The result of a query run inside a transaction.

execute() → None

Do nothing: the query ran, and its rows were read, before this result was returned.

rows() → list[Any]

Get the query’s rows.

Returns:

The rows, all of them, already read.

Return type:

list[Any]

class couchbase.transactions.TransactionResult

The outcome of a transaction that committed.

property transaction_id: str

The transaction’s ID.

property unstaging_complete: bool

Whether every change the transaction made was visible when it returned.

When False the transaction has committed, and cleanup makes the remaining changes visible.

This module also publishes these, described where they are first documented:

couchbase.transactions.transactions_get_multi

class couchbase.transactions.transactions_get_multi.TransactionMultiContentProxy(content_as_index: Callable[[int], Any])

What a transactional multi-document read’s content_as returns.

content_as[dict](0) is the first document as a dict.

This module also publishes these, described where they are first documented: