Core API

Cluster 

class couchbase_columnar.cluster.Cluster(connstr: 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 a Columnar cluster.

Important

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

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

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

Create a Cluster 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.
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:

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 couchbase_columnar.cluster import Cluster
from couchbase_columnar.credential import Credential

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

Initialize cluster using with global timeout options:

from datetime import timedelta

from couchbase_columnar.cluster import Cluster
from couchbase_columnar.credential import Credential
from couchbase_columnar.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('couchbases://hostname', cred, opts)

database(name: str)

Creates a database instance.

See also

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

Simple query with named parameters:

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

Retrieve metadata and/or metrics from query:

from couchbase_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}))
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_columnar.database.Database(cluster: Cluster, database_name: str)

Create a Database instance.

The database instance exposes the operations which are available to be performed against a Columnar 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_columnar.scope.Scope(database: Database, scope_name: str)

Create a Scope instance.

The Scope instance exposes the operations which are available to be performed against a Columnar 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 a Capella Columnar scope.

Note

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

See also

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

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

Simple query with named parameters:

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

Retrieve metadata and/or metrics from query:

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