Query (SQL++)

Enumerations

enum couchbase.n1ql.QueryProfile(value)

Specifies the profiling mode for a query.

Warning

Importing QueryProfile from couchbase.cluster is deprecated. QueryProfile should be imported from couchbase.n1ql.

Valid values are as follows:

OFF = <QueryProfile.OFF: 'off'>
PHASES = <QueryProfile.PHASES: 'phases'>
TIMINGS = <QueryProfile.TIMINGS: 'timings'>
enum couchbase.n1ql.QueryScanConsistency(value)

Represents the various scan consistency options that are available when querying against the query service.

Warning

Importing QueryScanConsistency from couchbase.cluster is deprecated. QueryScanConsistency should be imported from couchbase.n1ql.

Valid values are as follows:

NOT_BOUNDED = <QueryScanConsistency.NOT_BOUNDED: 'not_bounded'>
REQUEST_PLUS = <QueryScanConsistency.REQUEST_PLUS: 'request_plus'>
AT_PLUS = <QueryScanConsistency.AT_PLUS: 'at_plus'>
enum couchbase.n1ql.QueryStatus(value)

Represents the status of a query.

Valid values are as follows:

RUNNING = <QueryStatus.RUNNING: 'running'>
SUCCESS = <QueryStatus.SUCCESS: 'success'>
ERRORS = <QueryStatus.ERRORS: 'errors'>
COMPLETED = <QueryStatus.COMPLETED: 'completed'>
STOPPED = <QueryStatus.STOPPED: 'stopped'>
TIMEOUT = <QueryStatus.TIMEOUT: 'timeout'>
CLOSED = <QueryStatus.CLOSED: 'closed'>
FATAL = <QueryStatus.FATAL: 'fatal'>
ABORTED = <QueryStatus.ABORTED: 'aborted'>
UNKNOWN = <QueryStatus.UNKNOWN: 'unknown'>

Options

class couchbase.options.QueryOptions(timeout=None, read_only=None, scan_consistency=None, adhoc=None, client_context_id=None, max_parallelism=None, positional_parameters=None, named_parameters=None, pipeline_batch=None, pipeline_cap=None, profile=None, query_context=None, scan_cap=None, scan_wait=None, metrics=None, flex_index=None, preserve_expiry=None, use_replica=None, consistent_with=None, send_to_node=None, raw=None, span=None, serializer=None)

Available options to for a N1QL (SQL++) query.

Warning

Importing options from couchbase.cluster is deprecated. All options should be imported from couchbase.options.

Parameters:

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to global query operation timeout.

  • read_only (bool, optional) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data. Defaults to False.

  • scan_consistency (QueryScanConsistency, optional) – Specifies the consistency requirements when executing the query.

  • adhoc (bool, optional) – Specifies whether this is an ad-hoc query, or if it should be prepared for faster execution in the future. Defaults to True.

  • client_context_id (str, optional) – The returned client context id for this query. Defaults to None.

  • max_parallelism (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option. Defaults to None.

  • positional_parameters (Iterable[JSONType], optional) – Positional values to be used for the placeholders within the query. Defaults to None.

  • named_parameters (Iterable[Dict[str, JSONType]], optional) – Named values to be used for the placeholders within the query. Defaults to None.

  • pipeline_batch (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option. Defaults to None.

  • pipeline_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option. Defaults to None.

  • profile (QueryProfile, optional) – Specifies the level of profiling that should be used for the query. Defaults to Off.

  • query_context (str, optional) – Specifies the context within which this query should be executed. This can be scoped to a scope or a collection within the dataset. Defaults to None.

  • scan_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option. Defaults to None.

  • scan_wait (timedelta, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option. Defaults to None.

  • metrics (bool, optional) – Specifies whether metrics should be captured as part of the execution of the query. Defaults to False.

  • flex_index (bool, optional) – Specifies whether flex-indexes should be enabled. Allowing the use of full-text search from the query service. Defaults to False.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • use_replica (bool, optional) – Specifies that the query engine should use replica nodes for KV fetches if the active node is down. Defaults to None.

  • consistent_with (MutationState, optional) – Specifies a MutationState which the query should be consistent with. Defaults to None.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific N1QL operation. Defaults to DefaultJsonSerializer.

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

Results

QueryMetaData

class couchbase.n1ql.QueryMetaData(raw)
client_context_id() → str

Get the client context id which is assoicated with the executed query.

Returns:

The client context id which is assoicated with the executed query.

Return type:

str

errors() → List[QueryError]

Get errors that occurred during the execution of the query.

Returns:

Any errors that occurred during the execution of the query.

Return type:

List[QueryWarning]

metrics() → QueryMetrics | None

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

Returns:

A QueryMetrics instance.

Return type:

Optional[QueryMetrics]

profile() → str | int | float | bool | None | Dict[str, Any] | List[Any]

Get the various profiling details that were generated during execution of the query.

Returns:

Profiling details.

Return type:

Optional[JSONType]

request_id() → str

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

Returns:

The request ID which is associated with the executed query.

Return type:

str

signature() → str | int | float | bool | None | Dict[str, Any] | List[Any]

Provides the signature of the query.

Returns:

The signature of the query.

Return type:

Optional[JSONType]

status() → QueryStatus

Get the status of the query at the time the query meta-data was generated.

Returns:

The status of the query at the time the query meta-data was generated.

Return type:

QueryStatus

warnings() → List[QueryWarning]

Get warnings that occurred during the execution of the query.

Returns:

Any warnings that occurred during the execution of the query.

Return type:

List[QueryWarning]

QueryMetrics

class couchbase.n1ql.QueryMetrics(raw)
elapsed_time() → timedelta

Get the total amount of time spent running the query.

Returns:

The total amount of time spent running the query.

Return type:

timedelta

error_count() → UnsignedInt64

Get the total number of errors which were encountered during the execution of the query.

Returns:

The total number of errors which were encountered during the execution of the query.

Return type:

UnsignedInt64

execution_time() → timedelta

Get the total amount of time spent executing the query.

Returns:

The total amount of time spent executing the query.

Return type:

timedelta

mutation_count() → UnsignedInt64

Get the total number of rows which were altered by the query.

Returns:

The total number of rows which were altered by the query.

Return type:

UnsignedInt64

result_count() → UnsignedInt64

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

Returns:

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

Return type:

UnsignedInt64

result_size() → UnsignedInt64

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

Returns:

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

Return type:

UnsignedInt64

sort_count() → UnsignedInt64

Get the total number of rows which were part of the sorting for the query.

Returns:

The total number of rows which were part of the sorting for the query.

Return type:

UnsignedInt64

warning_count() → UnsignedInt64

Get the total number of warnings which were encountered during the execution of the query.

Returns:

The total number of warnings which were encountered during the execution of the query.

Return type:

UnsignedInt64

QueryResult

class couchbase.result.QueryResult
rows()

The rows which have been returned by the query.

Note

If using the acouchbase API be sure to use async for when looping over rows.

Returns:

Either an iterable or async iterable.

Return type:

Iterable

metadata()

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

Returns:

An instance of QueryMetaData.

Return type:

QueryMetaData