Core API

AsyncCluster 

class acouchbase_columnar.cluster.AsyncCluster(connstr: str, credential: Credential, options: ClusterOptions | None = None, loop: AbstractEventLoop | None = None, **kwargs: object)

Create an AsyncCluster instance.

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

Important

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

Parameters:

connstr (str) – The connection string to use for connecting to the cluster. The format of the connection string is the scheme (couchbases as TLS enabled connections are _required_), followed a hostname
credential (Credential) – User credentials.
loop (Optional[AbstractEventLoop]) – The asycio event loop.
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 connstr is provided.
ValueError – If incorrect options are provided.

Important

See AsyncCluster Overloads for details on overloaded methods.

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

Create an AsyncCluster instance

Parameters:

connstr (str) – The connection string to use for connecting to the cluster. The format of the connection string is the scheme (couchbases as TLS enabled connections are _required_), followed a hostname
credential (Credential) – User credentials.
loop (Optional[AbstractEventLoop]) – The asycio event loop.
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:

A Capella Columnar Cluster instance.

Raises:

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

Examples

Initialize cluster using default options:

from acouchbase_columnar import get_event_loop
from acouchbase_columnar.cluster import AsyncCluster
from acouchbase_columnar.credential import Credential

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

if __name__ == '__main__':
    loop = get_event_loop()
    loop.run_until_complete(main())

Initialize cluster using with global timeout options:

from datetime import timedelta

from acouchbase_columnar import get_event_loop
from acouchbase_columnar.cluster import AsyncCluster
from acouchbase_columnar.credential import Credential
from acouchbase_columnar.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('couchbases://hostname', cred, opts)
    # ... other async code ...

if __name__ == '__main__':
    loop = get_event_loop()
    loop.run_until_complete(main())

database(name: str)

Creates a database instance.

See also

acouchbase_columnar.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_columnar.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_columnar.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_columnar.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()}')

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_columnar.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_columnar.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 a Capella Columnar scope.

Note

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

See also

acouchbase_columnar.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_columnar.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_columnar.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_columnar.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 