N1QL Queries

class couchbase.cluster.QueryOptions[source]

QueryOptions Various options for queries

  • timeout (timedelta) – Uses this timeout value, rather than the default for the cluster. See query_timeout().

  • read_only (bool) – Hint to the server that this is a read-only query.

  • scan_consistency (QueryScanConsistency) – Specify the level of consistency for the query. Overrides any setting in consistent_with. Can be either NOT_BOUNDED(), which means return what is in the index now, or REQUEST_PLUS(), which means you can read your own writes. Slower, but when you need it you have it.

  • adhoc (bool) – Specifies if the prepared statement logic should be executed internally.

  • client_context_id (str) – Specifies a context ID string which is mirrored back from the query engine on response.

  • consistent_with (MutationState) – Specifies custom scan consistency through “at_plus” with mutation state token vectors.

  • max_parallelism (int) – The maximum number of logical cores to use in parallel for this query.

  • positional_parameters (Iterable[JSON]) – Specifies the parameters used in the query, when positional notation ($1, $2, etc…) is used.

  • named_parameters (dict[str,JSON]) – Specifies the parameters used in the query, when named parameter notation ($foo, $bar, etc…) is used.

  • pipeline_batch (int) – Specifies pipeline batching characteristics.

  • pipeline_cap (int) – Specifies pipeline cap characteristics.

  • profile (QueryProfile) – Specifies the profiling level to use.

  • query_context (str) – Specifies the context for the query.

  • raw (dict[str,JSON]) – This is a way to to specify the query payload to support unknown commands and be future-compatible.

  • scan_wait (timedelta) – Specifies maximum amount of time to wait for a scan.

  • scan_cap (int) – Specifies the scan cap characteristics.

  • metrics (bool) – Specifies whether or not to include metrics with the QueryResult.

:param bool flex_index

Specifies whether this query may make use of Search indexes

:param CouchbaseSpan span

Specifies the parent span for this query

class couchbase.cluster.QueryScanConsistency[source]
.. autodata:: NOT_BOUNDED
.. autodata:: REQUEST_PLUS
class couchbase.mutation_state.MutationState(*docs)[source]


The API and implementation of this class are subject to change.

This class acts as a container for one or more mutations. It may then be used with the consistent_with() method to indicate that a given query should be bounded by the contained mutations.

Using consistent_with is similar to setting consistency to REQUEST_PLUS, but is more optimal as the query will use cached data, except when the given mutation(s) are concerned. This option is useful for use patterns when an application has just performed a mutation, and wishes to perform a query in which the newly-performed mutation should reflect on the query results.


This feature requires Couchbase Server 4.5 or greater, and is enabled by default with 3.x SDKs. To disable, set the enable_mutation_tokens option in the couchbase.cluster.ClusterOptions to False

cluster = Cluster('couchbase://localhost',
            authenticator=PasswordAuthenticator('Administrator', 'password'))
bucket = cluster.bucket('default')
collection = bucket.default_collection()

rv = collection.upsert('foo': {'type': 'user', 'value': 'a foo value'})
ms = MutationState(res)
q_opts = QueryOptions(consistent_with=ms)
q_str = 'SELECT type, value FROM default WHERE type="user"'
query_iter = cluster.query(q_str, q_opts)

for row in query_iter.rows():
    # ...
class couchbase.n1ql.QueryResult[source]
__init__(params, parent, **kwargs)[source]

Object representing the execution of the request on the server.


You should typically not call this constructor by yourself, rather use the n1ql_query() method (or one of its async derivatives).

  • params – An _N1QLQuery object.

  • parent – The parent Client object

  • row_factory – Callable which accepts the raw dictionary of each row, and can wrap them in a customized class. The default is simply to return the dictionary itself.

To actually receive results of the query, iterate over this object.

class couchbase.n1ql.QueryMetrics[source]
class couchbase.n1ql.QueryWarning[source]
class couchbase.n1ql.QueryStatus[source]
__init__(*args, **kwargs)
class couchbase.n1ql.QueryMetaData[source]