Core API

Cluster 

class couchbase_analytics.cluster.Cluster(endpoint: str, credential: Credential, options: ClusterOptions | None = None, **kwargs: object)

Create a Cluster instance.

The cluster instance exposes the operations which are available to be performed against an Analytics cluster.

Important

Use the static Cluster.create_instance() method to create a Cluster.

Parameters:

endpoint (str) – The endpoint to use for sending HTTP requests to the Analytics server. The format of the endpoint string is the scheme (http or https is required, use https for TLS enabled connections), followed a hostname and optional port.
credential (Credential) – User credentials.
options (Optional[ClusterOptions]) – Global options to set for the cluster. Some operations allow the global options to be overriden by passing in options to the operation.
**kwargs (object) – keyword arguments that can be used in place or to overrride provided ClusterOptions

Raises:

ValueError – If incorrect endpoint is provided.
ValueError – If incorrect options are provided.

Important

See Cluster Overloads for details on overloaded methods.

classmethod create_instance(endpoint: str, credential: Credential, options: ClusterOptions | None = None, **kwargs: object)

Create a Cluster instance

Important

The appropriate port needs to be specified. The SDK’s default ports are 80 (http) and 443 (https). If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https).

Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095

Parameters:

endpoint (str) – The endpoint to use for sending HTTP requests to the Analytics server. The format of the endpoint string is the scheme (http or https is required, use https for TLS enabled connections), followed a hostname and optional port.
credential (Credential) – User credentials.
options (Optional[ClusterOptions]) – Global options to set for the cluster. Some operations allow the global options to be overriden by passing in options to the operation.
**kwargs (object) – Keyword arguments that can be used in place or to overrride provided ClusterOptions

Return type:

Cluster

Returns:

An Analytics Cluster instance.

Raises:

ValueError – If incorrect endpoint is provided.
ValueError – If incorrect options are provided.

Examples

Initialize cluster using default options:

from couchbase_analytics.cluster import Cluster
from couchbase_analytics.credential import Credential

cred = Credential.from_username_and_password('username', 'password')
cluster = Cluster.create_instance('https://hostname', cred)

Initialize cluster using with global timeout options:

from datetime import timedelta

from couchbase_analytics.cluster import Cluster
from couchbase_analytics.credential import Credential
from couchbase_analytics.options import ClusterOptions, ClusterTimeoutOptions

cred = Credential.from_username_and_password('username', 'password')
opts = ClusterOptions(timeout_options=ClusterTimeoutOptions(query_timeout=timedelta(seconds=120)))
cluster = Cluster.create_instance('https://hostname', cred, opts)

database(name: str)

Creates a database instance.

See also

couchbase_analytics.Scope.execute_query(): For how to execute scope-level queries.

Parameters:

statement (str) – The SQL++ statement to execute.
options (QueryOptions) – Optional parameters for the query operation.
**kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided QueryOptions

Returns:

An instance of a BlockingQueryResult which provides access to iterate over the query results and access metadata and metrics about the query.

Return type:

BlockingQueryResult

Examples

Simple query:

q_str = 'SELECT * FROM `travel-sample`.inventory.airline WHERE country LIKE 'United%' LIMIT 2;'
q_res = cluster.execute_query(q_str)
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with positional parameters:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample`.inventory.airline WHERE country LIKE $1 LIMIT $2;'
q_res = cluster.execute_query(q_str, QueryOptions(positional_parameters=['United%', 5]))
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample`.inventory.airline WHERE country LIKE $country LIMIT $lim;'
q_res = cluster.execute_query(q_str, QueryOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = cluster.execute_query(q_str, QueryOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

print(f'Query metadata: {q_res.metadata()}')
print(f'Query metrics: {q_res.metadata().metrics()}')

shutdown(): Shuts down this cluster instance. Cleaning up all resources associated with it. :rtype: None

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.

Database 

class couchbase_analytics.database.Database(cluster: Cluster, database_name: str)

Create a Database instance.

The database instance exposes the operations which are available to be performed against an Analytics database.

Parameters:

cluster (Cluster) – A Cluster instance.
database_name (str) – The database name.

property name: str

The name of this Database instance.

Type:: str

scope(scope_name: str)

Creates a Scope instance.

Parameters:: scope_name (str) – Name of the scope.
Return type:: Scope
Returns:: Scope

Scope 

class couchbase_analytics.scope.Scope(database: Database, scope_name: str)

Create a Scope instance.

The Scope instance exposes the operations which are available to be performed against an Analytics scope.

Parameters:

database (Database) – A Database instance.
scope_name (str) – The scope name.

property name: str

The name of this Scope instance.

Type:: str

Important

See Scope Overloads for details on overloaded methods.

execute_query(statement: str, *args: object, **kwargs: object)

Executes a query against an Analytics scope.

Note

A departure from the operational SDK, the query is NOT executed lazily.

See also

couchbase_analytics.Cluster.execute_query(): For how to execute cluster-level queries.

Parameters:

statement (str) – The N1QL statement to execute.
options (QueryOptions) – Optional parameters for the query operation.
**kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided QueryOptions

Returns:

An instance of a BlockingQueryResult which provides access to iterate over the query results and access metadata and metrics about the query.

Return type:

BlockingQueryResult

Examples

Simple query:

q_str = 'SELECT * FROM airline WHERE country LIKE 'United%' LIMIT 2;'
q_res = scope.execute_query(q_str)
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with positional parameters:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM airline WHERE country LIKE $1 LIMIT $2;'
q_res = scope.execute_query(q_str, QueryOptions(positional_parameters=['United%', 5]))
for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM airline WHERE country LIKE $country LIMIT $lim;'
q_res = scope.execute_query(q_str, QueryOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from couchbase_analytics.options import QueryOptions

# ... other code ...

q_str = 'SELECT * FROM `travel-sample` WHERE country LIKE $country LIMIT $lim;'
q_res = scope.execute_query(q_str, QueryOptions(named_parameters={'country': 'United%', 'lim':2}))
for row in q_res.rows():
    print(f'Found row: {row}')

print(f'Query metadata: {q_res.metadata()}')
print(f'Query metrics: {q_res.metadata().metrics()}')

Core API

Cluster

Database

Scope

Cluster 

Database 

Scope 