Results

class couchbase.result.AnalyticsResult(analytics_request: _Rows[object, AnalyticsMetaData])

The result of an analytics query: its rows, read by iterating it, then its metadata.

metadata() → AnalyticsMetaData | None

Get the metadata the service returned after the analytics query’s rows.

Returns:

The metadata, or None until every row has been read.

Return type:

AnalyticsMetaData | None

rows() → RowIterator[Any, AnalyticsMetaData]

The rows which have been returned by the analytics query.

Note

While iterating waits on the server, a pending KeyboardInterrupt is checked for once per the request’s timeout, so it can take up to that long to arrive.

Returns:

An iterable over the analytics query’s rows.

Return type:

Iterable

class couchbase.result.ClusterInfoResult(record: _ClusterInfoRecord)

What the cluster reports about its nodes, buckets and version.

The version is known only when every node runs the same one.

property is_community: bool | None

Whether the cluster is Community Edition, or None if that is not known.

property is_enterprise: bool | None

Whether the cluster is Enterprise Edition, or None if that is not known.

property nodes: list[_ClusterNodeDict]

The cluster’s nodes, each as a dict of its UUID, node name, status, hostname, OS, version and services.

property server_version: str | None

The cluster’s version as major.minor.patch-build, if known.

property server_version_build: int | None

The build number of the cluster’s version, if known.

property server_version_full: str | None

The cluster’s version as the server spells it, if known.

property server_version_short: float | None

The cluster’s version as major.minor, if known.

class couchbase.result.ContentProxy(content: Any)

What a result’s content_as returns: content_as[dict] is the content as a dict.

class couchbase.result.ContentSubdocProxy(serializer: Serializer, fields: tuple[_LookupInFieldRecord | _MutateInFieldRecord, ...])

What a sub-document result’s content_as returns: content_as[dict](0) is the first field as a dict.

class couchbase.result.CounterResult(record: _CounterRecord, key: str | None = None)

The result of incrementing or decrementing a counter document.

property cas: int

The CAS of the document.

Deprecated since version 4.0.3.

property content: int

The value of the document after the operation completed.

class couchbase.result.DiagnosticsResult(record: _DiagnosticsRecord)

The state of the SDK’s connections to the cluster, as diagnostics reports it.

as_json() → str

Get the report as JSON.

Returns:

The report as a JSON string.

Return type:

str

property cas: int

Always 0.

Deprecated since version 4.7.0.

property endpoints: dict[ServiceType, list[EndpointDiagnosticsReport]]

The report on each endpoint, by service.

property flags: int

Always 0.

Deprecated since version 4.7.0.

property id: str

The report’s ID.

property key: str | None

Always None.

Deprecated since version 4.7.0.

property sdk: str

The name of the SDK which generated this report.

property state: ClusterState

The state of the SDK’s connections, summed over every endpoint.

property success: bool

Always False, whatever the report says of the cluster.

Deprecated since version 4.7.0.

property value: Any | None

Always None.

Deprecated since version 4.7.0.

property version: int

The version of the report’s format.

class couchbase.result.ExistsResult(record: _ExistsRecord, key: str | None = None)

The result of checking whether a document exists.

property exists: bool

Whether the document exists.

property flags: int

The document’s flags, which the transcoder reads to decode it.

class couchbase.result.GetReplicaResult(record: _GetReplicaRecord, transcoder: Transcoder | None = None, key: str | None = None)

The result of reading a document from the active node or a replica.

property content_as: ContentProxy

The contents of the document.

Get the value as a dict:

res = collection.get_replica(key)
value = res.content_as[dict]
property flags: int

The document’s flags, which the transcoder reads to decode it.

property is_active: bool

Whether the document was read from the active node.

Deprecated since version 4.0.3: Use is_replica instead.

property is_replica: bool

Whether the document was read from a replica.

class couchbase.result.GetResult(record: _GetRecord, transcoder: Transcoder | None = None, key: str | None = None)

The result of reading a document.

property content_as: ContentProxy

The contents of the document.

Get the value as a dict:

res = collection.get(key)
value = res.content_as[dict]
property expiryTime: datetime | None

The expiry of the document, if it was requested.

Deprecated since version 4.0.0: Use expiry_time instead.

property expiry_time: datetime | None

The expiry of the document, if it was requested.

property flags: int

The document’s flags, which the transcoder reads to decode it.

class couchbase.result.LookupInReplicaResult(record: _LookupInReplicaRecord, serializer: Serializer, key: str | None = None)

The result of reading paths within a document from the active node or a replica.

property content_as: ContentSubdocProxy

A proxy to return the value at the specified index.

Get first value as a dict:

res = collection.lookup_in(key, (SD.get("geo"), SD.exists("city")))
value = res.content_as[dict](0)
exists(index: int) → bool

Check if the subdocument path exists.

Raises:

InvalidIndexException – If the provided index is out of range.

Returns:

True if the path exists. False if the path does not exist.

Return type:

bool

property is_replica: bool

Whether the document was read from a replica.

class couchbase.result.LookupInResult(record: _LookupInRecord, serializer: Serializer, key: str | None = None)

The result of reading paths within a document.

property content_as: ContentSubdocProxy

A proxy to return the value at the specified index.

Get first value as a dict:

res = collection.lookup_in(key, (SD.get("geo"), SD.exists("city")))
value = res.content_as[dict](0)
exists(index: int) → bool

Check if the subdocument path exists.

Raises:

InvalidIndexException – If the provided index is out of range.

Returns:

True if the path exists. False if the path does not exist.

Return type:

bool

class couchbase.result.MultiCounterResult(results: dict[str, CounterResult | CouchbaseException], all_ok: bool)

The result of increment_multi or decrement_multi.

property all_ok: bool

Whether every key’s operation succeeded.

property exceptions: dict[str, CouchbaseException]

The exception each failed key’s operation raised, by key.

property results: dict[str, CounterResult]

The result of each key whose operation succeeded, by key.

class couchbase.result.MultiExistsResult(results: dict[str, ExistsResult | CouchbaseException], all_ok: bool)

The result of exists_multi.

property all_ok: bool

Whether every key’s operation succeeded.

property exceptions: dict[str, CouchbaseException]

The exception each failed key’s operation raised, by key.

property results: dict[str, ExistsResult]

The result of each key whose operation succeeded, by key.

class couchbase.result.MultiGetReplicaResult(results: dict[str, _ReplicaValueType | CouchbaseException], all_ok: bool)

The result of get_any_replica_multi or get_all_replicas_multi.

property results: dict[str, _ReplicaValueType]

The result of each key whose operation succeeded, by key.

A GetReplicaResult for get_any_replica_multi, a list of them for get_all_replicas_multi.

class couchbase.result.MultiGetResult(results: dict[str, GetResult | CouchbaseException], all_ok: bool)

The result of get_multi.

property results: dict[str, GetResult]

The result of each key whose operation succeeded, by key.

class couchbase.result.MultiMutationResult(results: dict[str, MutationResult | CouchbaseException], all_ok: bool)

The result of a multi-key mutation such as upsert_multi or remove_multi.

property all_ok: bool

Whether every key’s operation succeeded.

property exceptions: dict[str, CouchbaseException]

The exception each failed key’s operation raised, by key.

property results: dict[str, MutationResult]

The result of each key whose operation succeeded, by key.

class couchbase.result.MultiResult(results: dict[str, Any], all_ok: bool, result_type: type[GetReplicaResult] | type[GetResult])

The base of the results of get_multi and the replica *_multi operations.

property all_ok: bool

Whether every key’s operation succeeded.

property exceptions: dict[str, CouchbaseException]

The exception each failed key’s operation raised, by key.

couchbase.result.MultiResultType = couchbase.common.result.MultiGetResult | couchbase.common.result.MultiMutationResult

Represent a PEP 604 union type

E.g. for int | str

class couchbase.result.MutateInResult(record: _MutateInRecord, serializer: Serializer, key: str | None = None)

The result of changing paths within a document.

property content_as: ContentSubdocProxy

A proxy to return the value at the specified index.

Get first value as a str:

res = collection.mutate_in(key, (SD.upsert("city", "New City"),
                                SD.replace("faa", "CTY")))
value = res.content_as[str](0)
class couchbase.result.MutationResult(record: _MutationRecord | _CounterRecord | _MutateInRecord, key: str | None = None)

The result of an operation that changed a document.

mutation_token() → MutationToken | None

Get the operation’s mutation token, if it has one.

Returns:

The operation’s mutation token.

Return type:

MutationToken | None

class couchbase.result.MutationToken(token: _MutationTokenDict)

Identifies one mutation, so a later query or search can be made consistent with it.

Warning

couchbase.mutation_state.MutationToken is deprecated, and will be removed in a future release. Import MutationToken from couchbase.result.

Pass it to MutationState.

as_dict() → _MutationTokenDict

Get the token’s fields as a dict.

Returns:

The token’s fields, by name.

Return type:

dict[str, int | str]

as_tuple() → tuple[int, int, int, str]

Get the token’s fields as a tuple.

Returns:

The partition ID, partition UUID, sequence number and bucket name.

Return type:

tuple[int, int, int, str]

property bucket_name: str

The name of the bucket the document is in.

property partition_id: int

The ID of the partition the document is in.

property partition_uuid: int

The UUID of the partition’s history when the mutation was made.

property sequence_number: int

The mutation’s sequence number within the partition.

class couchbase.result.OperationResult(cas: int | None, mut_token: MutationToken | None)

The CAS and mutation token of an operation.

Deprecated since version 4.0.0.

property cas: int | None

The CAS of the document.

mutation_token() → MutationToken | None

Get the operation’s mutation token, if it has one.

Returns:

The operation’s mutation token.

Return type:

MutationToken | None

class couchbase.result.PingResult(record: _PingRecord)

The outcome of pinging the cluster’s services, as ping reports it.

as_json() → str

Get the report as JSON.

Returns:

The report as a JSON string.

Return type:

str

property cas: int

Always 0.

Deprecated since version 4.7.0.

property endpoints: dict[ServiceType, list[EndpointPingReport]]

The report on each endpoint pinged, by service.

property flags: int

Always 0.

Deprecated since version 4.7.0.

property id: str

The report’s ID.

property key: str | None

Always None.

Deprecated since version 4.7.0.

property sdk: str

The name of the SDK which generated this report.

property success: bool

Always False, whatever the report says of the cluster.

Deprecated since version 4.7.0.

property value: Any | None

Always None.

Deprecated since version 4.7.0.

property version: int

The version of the report’s format.

class couchbase.result.QueryResult(n1ql_request: _Rows[_ExecuteT, QueryMetaData])

The result of a query: its rows, read by iterating it, then its metadata.

execute() → _ExecuteT

Read every row of the query.

Returns:

The rows. On the asyncio API, a task that resolves to them.

Return type:

list[Any]

Example:

rows = cluster.query("SELECT * FROM `travel-sample` WHERE country LIKE 'United%' LIMIT 2").execute()
metadata() → QueryMetaData | None

Get the metadata the service returned after the query’s rows.

Returns:

The metadata, or None until every row has been read.

Return type:

QueryMetaData | None

rows() → RowIterator[Any, QueryMetaData]

The rows which have been returned by the query.

Note

While iterating waits on the server, a pending KeyboardInterrupt is checked for once per the request’s timeout, so it can take up to that long to arrive.

Returns:

An iterable over the query’s rows.

Return type:

Iterable

class couchbase.result.Result(record: Any, transcoder: Transcoder | None = None, key: str | None = None)

The base of the results of the key-value operations.

property cas: int

The CAS of the document.

property flags: int

The document’s flags, which the transcoder reads to decode it.

property key: str | None

The key of the document the operation was on, if known.

property success: bool

Whether the operation succeeded.

property value: Any

The content of the document, if it exists.

class couchbase.result.ScanResult(record: _ScanItemRecord, ids_only: bool, transcoder: Transcoder | None)

One document a range scan returned.

property cas: int

The CAS of the document.

property content_as: ContentProxy

The contents of the document.

Get the value as a dict:

for res in collection.scan(RangeScan()):
    value = res.content_as[dict]
Raises:

InvalidArgumentException – If the scan was asked for IDs only.

property expiry_time: datetime | None

The expiry of the document, if it was requested.

property flags: int

The document’s flags, which the transcoder reads to decode it.

property id: str

The document’s ID.

property ids_only: bool

Whether the scan was asked for IDs only, in which case the result carries no document.

class couchbase.result.ScanResultIterable(rows: object, executor: _ScanCanceller)

The documents a range scan returns, read by iterating it.

cancel_scan() → None

Cancel the scan. Iterating its rows then ends at the next row the scan would return.

rows() → RowIterator[ScanResult, None]

Get the documents the scan returns.

Returns:

An iterable over the documents.

Return type:

Iterable

class couchbase.result.SearchResult(search_request: _Rows[object, _SearchFinalMetadata])

The result of a search: its rows, read by iterating it, then its metadata and facets.

facets() → dict[str, SearchFacetResult] | None

Get the results of the search’s facets, which the service returns after its rows.

Returns:

Each facet’s result, by the facet’s name, or None until every row has been read.

Return type:

dict[str, SearchFacetResult] | None

metadata() → SearchMetaData | None

Get the metadata the service returned after the search’s rows.

Returns:

The metadata, or None until every row has been read.

Return type:

SearchMetaData | None

rows() → RowIterator[SearchRow, _SearchFinalMetadata]

The rows which have been returned by the search query.

Note

While iterating waits on the server, a pending KeyboardInterrupt is checked for once per the request’s timeout, so it can take up to that long to arrive.

Returns:

An iterable over the search query’s rows.

Return type:

Iterable

class couchbase.result.ValueResult(cas: int | None, mut_token: MutationToken | None, value: Any)

The CAS, mutation token and value of an operation.

Deprecated since version 4.0.0.

property cas: int | None

The CAS of the document.

mutation_token() → MutationToken | None

Get the operation’s mutation token, if it has one.

Returns:

The operation’s mutation token.

Return type:

MutationToken | None

property value: Any | None

The content of the document.

class couchbase.result.ViewResult(view_request: _Rows[object, ViewMetaData])

The result of a view query: its rows, read by iterating it, then its metadata.

metadata() → ViewMetaData | None

Get the metadata the service returned after the view query’s rows.

Returns:

The metadata, or None until every row has been read.

Return type:

ViewMetaData | None

rows() → RowIterator[ViewRow, ViewMetaData]

The rows which have been returned by the view query.

Note

While iterating waits on the server, a pending KeyboardInterrupt is checked for once per the request’s timeout, so it can take up to that long to arrive.

Returns:

An iterable over the view query’s rows.

Return type:

Iterable