N1QL Queries¶
- class couchbase.cluster.QueryOptions[source]¶
- __init__(**kwargs)[source]¶
QueryOptions Various options for queries
- Parameters
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, orREQUEST_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
- :param bool preserve_expiry
UNCOMMITTED preserve_expiry is an uncommitted API that is unlikely to change, but may still change as final consensus on its behavior has not yet been reached. Specifies whether this query will preserve expiry on mutation
- class couchbase.cluster.QueryScanConsistency[source]¶
- .. autodata:: NOT_BOUNDED
- .. autodata:: REQUEST_PLUS
- class couchbase.mutation_state.MutationState(*docs)[source]¶
Warning
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
toREQUEST_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.Note
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 Falsecluster = 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.
Warning
You should typically not call this constructor by yourself, rather use the
n1ql_query()
method (or one of its async derivatives).- Parameters
params – An
_N1QLQuery
object.parent – The parent
Client
objectrow_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.