Cluster
- class txcouchbase.cluster.Cluster(connstr: str, *options: ClusterOptions, **kwargs: Unpack[ClusterKwargs])
A connection to a Couchbase cluster, for use with Twisted.
Its operations return a Deferred. Create it on a running reactor and wait on
on_connect()before the first operation.- Parameters:
connstr (str) – The connection string for the cluster.
*options (
ClusterOptions) – Options for the cluster, including its authenticator.**kwargs – keyword arguments that can be used in place or to override provided
ClusterOptions
- analytics_indexes() AnalyticsIndexManager
Get a manager for the analytics dataverses, datasets, indexes and links of this cluster.
- Returns:
An
AnalyticsIndexManagerinstance.- Return type:
- analytics_query(statement: str, *options: AnalyticsOptions | str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], **kwargs: Any) Deferred[AnalyticsResult]
Executes an analaytics query against the cluster.
Note
The analytics query is sent when this is called, and the Deferred fires once the core has buffered the response, so iterating the
AnalyticsResultdoes not block the reactor.See also
AnalyticsIndexManager: for how to manage analytics dataverses, datasets, indexes and links.analytics_query(): for how to execute scope-level analytics queries
- Parameters:
statement (str) – The analytics SQL++ statement to execute.
options (
AnalyticsOptions) – Optional parameters for the analytics query operation.**kwargs – keyword arguments that can be used in place or to override provided
AnalyticsOptions. A keyword that is not one of its options is sent as a named parameter; preferAnalyticsOptions(named_parameters=...), which cannot collide with an option name.
- Returns:
An instance of a
AnalyticsResultwhich provides access to iterate over the analytics query results and access metadata and metrics about the analytics query.- Return type:
Deferred[
AnalyticsResult]
- bucket(bucket_name: str) Bucket
Creates a Bucket instance to a specific bucket.
See also
- Parameters:
bucket_name (str) – Name of the bucket to reference
- Returns:
A bucket instance
- Return type:
The bucket opens on the reactor once the cluster is connected, so this call does not raise. A bucket that cannot be opened, such as one that does not exist, fails the first operation on it, and the Deferred from
on_connect().
- buckets() BucketManager
Get a manager for the buckets of this cluster.
- Returns:
A
BucketManagerinstance.- Return type:
- close() Deferred[None]
Shuts down this cluster instance. Cleaning up all resources associated with it.
Warning
Use of this method is almost always unnecessary. Cluster resources should be cleaned up once the cluster instance falls out of scope. However, in some applications tuning resources is necessary and in those types of applications, this method might be beneficial.
- cluster_info() Deferred[ClusterInfoResult]
Retrieve the Couchbase cluster information.
Note
If using Couchbase Server version < 6.6, a bucket must be opened prior to calling cluster.cluster_info(). If a bucket is not opened a
ServiceUnavailableExceptionwill be raised.- Returns:
Information about the connected cluster.
- Return type:
Deferred[
ClusterInfoResult]- Raises:
ServiceUnavailableException – If called prior to connecting to a bucket if using server version < 6.6.
- diagnostics(opts: DiagnosticsOptions | None = None, **kwargs: Unpack[DiagnosticsOptionsKwargs]) Deferred[DiagnosticsResult]
Performs a diagnostic operation against the cluster.
The diagnostic operations returns a report about the current active connections with the cluster. Includes information about remote and local addresses, last activity, and other diagnostics information.
- Parameters:
opts (
DiagnosticsOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
DiagnosticsOptions
- Returns:
A report which describes current active connections with the cluster.
- Return type:
Deferred[
DiagnosticsResult]
- on_connect() Deferred[None]
Wait until the cluster is connected.
- Returns:
Fires once the cluster is connected, or fails if it cannot connect.
- Return type:
- ping(opts: PingOptions | None = None, **kwargs: Unpack[PingOptionsKwargs]) Deferred[PingResult]
Performs a ping operation against the cluster.
The ping operation pings the services which are specified (or all services if none are specified). Returns a report which describes the outcome of the ping operations which were performed.
- Parameters:
opts (
PingOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
PingOptions
- Returns:
A report which describes the outcome of the ping operations which were performed.
- Return type:
Deferred[
PingResult]
- query(statement: str, *options: QueryOptions | str | int | float | bool | None | Mapping[str, Any] | Sequence[Any], **kwargs: Any) Deferred[QueryResult]
Executes a N1QL query against the cluster.
Note
The query is sent when this is called, and the Deferred fires once the core has buffered the response, so iterating the
QueryResultdoes not block the reactor.See also
QueryIndexManager: for how to manage query indexesquery(): For how to execute scope-level queries.
- Parameters:
statement (str) – The N1QL statement to execute.
options (
QueryOptions) – Optional parameters for the query operation.**kwargs – keyword arguments that can be used in place or to override provided
QueryOptions. A keyword that is not one of its options is sent as a named parameter; preferQueryOptions(named_parameters=...), which cannot collide with an option name.
- Returns:
An instance of a
QueryResultwhich provides access to iterate over the query results and access metadata and metrics about the query.- Return type:
Deferred[
QueryResult]
- query_indexes() QueryIndexManager
Get a manager for the query indexes of this cluster.
- Returns:
A
QueryIndexManagerinstance.- Return type:
- search(index: str, request: SearchRequest | SearchQuery, options: SearchOptions | None = None, **kwargs: Unpack[SearchOptionsKwargs]) Deferred[SearchResult]
Executes an search against the cluster.
Note
The search is sent when this is called, and the Deferred fires once the core has buffered the response, so iterating the
SearchResultdoes not block the reactor.See also
SearchIndexManager: for how to manage search indexes.search(): for how to execute scope-level search
- Parameters:
index (str) – Name of the search index to use.
request (
SearchRequest|SearchQuery) –Type of search request to perform.
Deprecated since version 4.7.0: Passing a
SearchQueryis deprecated; wrap it withcreate()instead.options (
SearchOptions) – Optional parameters for the search query operation.**kwargs – keyword arguments that can be used in place or to override provided
SearchOptions
- Returns:
An instance of a
SearchResultwhich provides access to iterate over the search query results and access metadata and metrics about the search query.- Return type:
Deferred[
SearchResult]
- search_indexes() SearchIndexManager
Get a manager for the search indexes of this cluster.
- Returns:
A
SearchIndexManagerinstance.- Return type:
- search_query(index: str, query: SearchQuery, options: SearchOptions | None = None, **kwargs: Unpack[SearchOptionsKwargs]) Deferred[SearchResult]
Executes an search query against the cluster.
Deprecated since version 4.1.11: Use
search()instead.Note
The search query is sent when this is called, and the Deferred fires once the core has buffered the response, so iterating the
SearchResultdoes not block the reactor.See also
SearchIndexManager: for how to manage search indexes.
- Parameters:
index (str) – Name of the search query to use.
query (
SearchQuery) – Type of search query to perform.options (
SearchOptions) – Optional parameters for the search query operation.**kwargs – keyword arguments that can be used in place or to override provided
SearchOptions
- Returns:
An instance of a
SearchResultwhich provides access to iterate over the search query results and access metadata and metrics about the search query.- Return type:
Deferred[
SearchResult]- Raises:
InvalidArgumentException – If a
SearchRequestis provided. Usesearch()for a search request.
- users() UserManager
Get a manager for the users of this cluster.
- Returns:
A
UserManagerinstance.- Return type:
- wait_until_ready(timeout: timedelta, opts: WaitUntilReadyOptions | None = None, **kwargs: Unpack[WaitUntilReadyKwargs]) Deferred[None]
Wait until the cluster is ready for use.
Check the current connections to see if the desired state has been reached. If not, perform a ping against the specified services. The ping operation will be performed repeatedly with a slight delay in between until the specified timeout has been reached or the cluster is ready for use, whichever comes first.
See also
- Parameters:
timeout (timedelta) – Amount of time to wait for cluster to be ready before a
UnAmbiguousTimeoutExceptionis raised.opts (
WaitUntilReadyOptions) – Optional parameters for this operation.**kwargs – keyword arguments that can be used in place or to override provided
WaitUntilReadyOptions
- Raises:
UnAmbiguousTimeoutException – If the specified timeout is reached prior to the cluster being ready for use.