Query (SQL++)

Enumerations

enum acouchbase_analytics.query.QueryScanConsistency(value)

Represents the various scan consistency options that are available.

Valid values are as follows:

NOT_BOUNDED = <QueryScanConsistency.NOT_BOUNDED: 'not_bounded'>

Indicates that no specific consistency is required, this is the fastest options, but results may not include the most recent operations which have been performed.

REQUEST_PLUS = <QueryScanConsistency.REQUEST_PLUS: 'request_plus'>

Indicates that the results to the query should include all operations that have occurred up until the query was started. This incurs a performance penalty of waiting for the index to catch up to the most recent operations, but provides the highest level of consistency.

Options

class acouchbase_analytics.options.QueryOptions(**kwargs: Unpack[QueryOptionsKwargs])

Available options for Analytics query operation.

Timeout will default to cluster setting if not set for the operation.

Note

Options marked VOLATILE are subject to change at any time.

Parameters:

  • client_context_id (Optional[str]) – Set to configure a unique identifier for this query request. Defaults to None (autogenerated by client).

  • deserializer (Optional[Deserializer]) – Specifies a Deserializer to apply to results. Defaults to None (DefaultJsonDeserializer).

  • lazy_execute (Optional[bool]) – VOLATILE If enabled, the query will not execute until the application begins to iterate over results. Defaults to None (disabled).

  • max_retries (Optional[int]) – VOLATILE Set to configure the maximum number of retries for a request.

  • named_parameters (Optional[Dict[str, JSONType]]) – Values to use for named placeholders in query.

  • positional_parameters (Optional[List[JSONType]]) – Values to use for positional placeholders in query.

  • query_context (Optional[str]) – Specifies the context within which this query should be executed.

  • raw (Optional[Dict[str, Any]]) – Specifies any additional parameters which should be passed to the Analytics engine when executing the query.

  • readonly (Optional[bool]) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data.

  • scan_consistency (Optional[QueryScanConsistency]) – Specifies the consistency requirements when executing the query.

  • timeout (Optional[timedelta]) – Set to configure allowed time for operation to complete. Defaults to None (75s).

  • stream_config (Optional[JsonStreamConfig]) – VOLATILE Configuration for JSON stream processing. Defaults to None (default configuration). See JsonStreamConfig for details.

class acouchbase_analytics.options.StartQueryOptions(**kwargs: Unpack[StartQueryOptionsKwargs])

Available options for Analytics asynchronous server query operation.

Timeout will default to cluster setting if not set for the operation.

Note

Options marked VOLATILE are subject to change at any time.

Parameters:

  • client_context_id (Optional[str]) – Set to configure a unique identifier for this query request. Defaults to None (autogenerated by client).

  • max_retries (Optional[int]) – VOLATILE Set to configure the maximum number of retries for a request.

  • named_parameters (Optional[Dict[str, JSONType]]) – Values to use for named placeholders in query.

  • positional_parameters (Optional[List[JSONType]]) – Values to use for positional placeholders in query.

  • query_context (Optional[str]) – Specifies the context within which this query should be executed.

  • raw (Optional[Dict[str, Any]]) – Specifies any additional parameters which should be passed to the Analytics engine when executing the query.

  • readonly (Optional[bool]) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data.

  • scan_consistency (Optional[QueryScanConsistency]) – Specifies the consistency requirements when executing the query.

  • timeout (Optional[timedelta]) – Set to configure allowed time for operation to complete. Defaults to None (75s).

  • stream_config (Optional[JsonStreamConfig]) – VOLATILE Configuration for JSON stream processing. Defaults to None (default configuration). See JsonStreamConfig for details.

Results

AsyncQueryResult

class acouchbase_analytics.result.AsyncQueryResult
cancel()

Cancel streaming the query results.

VOLATILE This API is subject to change at any time.

Return type:

None

rows()

Retrieve the rows which have been returned by the query.

Note

Bee sure to use async for when looping over rows.

Return type:

AsyncIterator

Returns:

An async iterator for iterating over query results.

async get_all_rows()

Convenience method to load all query results into memory.

Return type:

List[Any]

Returns:

A list of query results.

Example

Read all rows from simple query:

q_str = 'SELECT * FROM `travel-sample`.inventory WHERE country LIKE 'United%' LIMIT 2;'
q_rows = await cluster.execute_query(q_str).get_all_rows()
metadata()

The meta-data which has been returned by the query.

Return type:

QueryMetadata

Returns:

A QueryMetadata instance (if available).

Raises:

RuntimeError – When the metadata is not available. Metadata is only available once all rows have been iterated.

QueryMetadata

class acouchbase_analytics.query.QueryMetadata
request_id()

Get the request ID which is associated with the executed query.

Return type:

str

Returns:

The request ID which is associated with the executed query.

warnings()

Get warnings that occurred during the execution of the query.

Return type:

List[QueryWarning]

Returns:

Any warnings that occurred during the execution of the query.

metrics()

Get the various metrics which are made available by the query engine.

Return type:

QueryMetrics

Returns:

A QueryMetrics instance.

QueryMetrics

class acouchbase_analytics.query.QueryMetrics
elapsed_time()

Get the total amount of time spent running the query.

Return type:

timedelta

Returns:

The total amount of time spent running the query.

execution_time()

Get the total amount of time spent executing the query.

Return type:

timedelta

Returns:

The total amount of time spent executing the query.

result_count()

Get the total number of rows which were part of the result set.

Return type:

int

Returns:

The total number of rows which were part of the result set.

result_size()

Get the total number of bytes which were generated as part of the result set.

Return type:

int

Returns:

The total number of bytes which were generated as part of the result set.

processed_objects()

Get the total number of objects that were processed to create the result set.

Return type:

int

Returns:

The total number of objects that were processed to create the result set.

QueryWarning

class acouchbase_analytics.query.QueryWarning
code()
Return type:

int

Returns:

The query warning code.

message()
Return type:

str

Returns:

The query warning message.