A newer version of this documentation is available.

View Latest

N1QL queries

You can perform N1QL queries via the Python client.
See Couchbase Developer documentation for a quick intro to N1QL: Querying with N1QL
To set the N1QL timeout values per query or globally, see timeouts.

To issue N1QL queries, you should create a couchbase.n1ql.N1QLQuery object, and pass it (as the query keyword argument) to the n1ql_query() method in the Bucket class. Simple queries (that is, ones that are only strings and do not use placeholders) can be supplied directly to the n1ql_query() function, which will implicitly create the N1QLQuery object internally.

The return value from n1ql_query() is a N1QLRequest object. Iterating over the object will yield the rows returned by the server for the given query (as a dict). Each row represents a row received for the query.

As a convenience for queries which are not intended to yield multiple rows, you may use the returned N1QLRequest object’s execute() method. For queries which are intended to return only a single result, you can use the get_single_result() method. Both of the aforementioned methods are wrappers that iterate over the object internally and are intended to provide additional clarity inside your application’s code.

Simple N1QL Query
bkt.n1ql_query('CREATE PRIMARY INDEX ON default').execute()
for row in bkt.n1ql_query('SELECT * FROM default'):
    print row

You can use N1QL placeholders in the query. Placeholders allow you to specify variable constraints for an otherwise constant query. To use placeholders, manually construct an N1QLQuery object with the base query string, and simply use keyword and positional arguments for named or positional placeholders, respectively:

N1QL Query with placeholders
from couchbase.n1ql import N1QLQuery
# ...
q = N1QLQuery('SELECT fname, lname, age FROM default WHERE age > $age', age=22)
for row in bkt.n1ql_query(q):
    print row