Core API

AsyncCluster 

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

Create an AsyncCluster instance.

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

Important

Use the static AsyncCluster.create_instance() method to create an AsyncCluster.

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 AsyncCluster Overloads for details on overloaded methods.

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

Create an AsyncCluster 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:

AsyncCluster

Returns:

An Analytics Cluster instance.

Raises:

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

Examples

Initialize cluster using default options:

import asyncio

from acouchbase_analytics.cluster import AsyncCluster
from acouchbase_analytics.credential import Credential

async def main() -> None:
    cred = Credential.from_username_and_password('username', 'password')
    cluster = AsyncCluster.create_instance('https://hostname', cred)
    # ... other async code ...

if __name__ == '__main__':
    asyncio.run(main())

Initialize cluster using with global timeout options:

import asyncio
from datetime import timedelta

from acouchbase_analytics import get_event_loop
from acouchbase_analytics.cluster import AsyncCluster
from acouchbase_analytics.credential import Credential
from acouchbase_analytics.options import ClusterOptions, ClusterTimeoutOptions

async def main() -> None:
    cred = Credential.from_username_and_password('username', 'password')
    opts = ClusterOptions(timeout_options=ClusterTimeoutOptions(query_timeout=timedelta(seconds=120)))
    cluster = AsyncCluster.create_instance('https://hostname', cred, opts)
    # ... other async code ...

if __name__ == '__main__':
    asyncio.run(main())

database(name: str)

Creates a database instance.

See also

acouchbase_analytics.AsyncScope.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:

A Future is returned. Once the Future completes, an instance of a AsyncQueryResult is available to provide access to iterate over the query results and access metadata and metrics about the query.

Return type:

Future[AsyncQueryResult]

Examples

Simple query:

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

Simple query with positional parameters:

from acouchbase_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]))
async for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from acouchbase_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}))
async for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from acouchbase_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}))
async 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()}')

async 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.

AsyncDatabase 

class acouchbase_analytics.database.AsyncDatabase(cluster: AsyncCluster, database_name: str)

property name: str

The name of this AsyncDatabase instance.

Type:: str

scope(scope_name: str)

Creates a AsyncScope instance.

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

AsyncScope 

class acouchbase_analytics.scope.AsyncScope(database: AsyncDatabase, scope_name: str)

property name: str

The name of this AsyncScope instance.

Type:: str

Important

See AsyncScope 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

acouchbase_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:

A Future is returned. Once the Future completes, an instance of a AsyncQueryResult is available to provide access to iterate over the query results and access metadata and metrics about the query.

Return type:

Future[AsyncQueryResult]

Examples

Simple query:

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

Simple query with positional parameters:

from acouchbase_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]))
async for row in q_res.rows():
    print(f'Found row: {row}')

Simple query with named parameters:

from acouchbase_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}))
async for row in q_res.rows():
    print(f'Found row: {row}')

Retrieve metadata and/or metrics from query:

from acouchbase_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}))
async 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

AsyncCluster

AsyncDatabase

AsyncScope

AsyncCluster 

AsyncDatabase 

AsyncScope 