query

API module for composing and executing Cloudant queries.

class cloudant.query.Query(database, **kwargs)

Bases: dict

Encapsulates a query as a dictionary based object, providing a sliceable and iterable query result collection that can be used to process query output data through the result attribute.

For example:

# Slicing to skip/limit:
query.result[100:200]
query.result[:200]
query.result[100:]
query.result[:]

# Iteration is supported via the result attribute:
for doc in query.result:
    print doc

The query result collection provides basic functionality, which can be customized with other arguments using the custom_result() context.

For example:

# Setting the read quorum as part of a custom result
with query.custom_result(r=3) as rslt:
    rslt[100:200] # slice the result

    # Iteration
    for doc in rslt:
        print doc

# Iteration over a query result sorted by the "name" field:
with query.custom_result(sort=[{'name': 'asc'}]) as rslt:
    for doc in rslt:
        print doc
Parameters:
  • database (CloudantDatabase) – A Cloudant database instance used by the Query.
  • bookmark (str) – A string that enables you to specify which page of results you require.
  • fields (list) – A list of fields to be returned by the query.
  • limit (int) – Maximum number of results returned.
  • r (int) – Read quorum needed for the result. Each document is read from at least ‘r’ number of replicas before it is returned in the results.
  • selector (dict) – Dictionary object describing criteria used to select documents.
  • skip (int) – Skip the first ‘n’ results, where ‘n’ is the value specified.
  • sort (list) – A list of fields to sort by. Optionally the list can contain elements that are single member dictionary structures that specify sort direction. For example sort=['name', {'age': 'desc'}] means to sort the query results by the “name” field in ascending order and the “age” field in descending order.
  • use_index (str) – Identifies a specific index for the query to run against, rather than using the Cloudant Query algorithm which finds what it believes to be the best index.
  • partition_key (str) – Optional. Specify a query partition key. Defaults to None resulting in global queries.
__call__(**kwargs)

Makes the Query object callable and retrieves the raw JSON content from the remote database based on the current Query definition, and any additional kwargs provided as query parameters.

For example:

# Construct a Query
query = Query(database, selector={'_id': {'$gt': 0}})
# Use query as a callable limiting results to 100,
# skipping the first 100.
for doc in query(limit=100, skip=100)['docs']:
    # Process query data (in JSON format).

Note: Rather than using the Query callable directly, if you wish to retrieve query results in raw JSON format use the provided database API of get_query_result() and set raw_result=True instead.

Parameters:
  • bookmark (str) – A string that enables you to specify which page of results you require.
  • fields (list) – A list of fields to be returned by the query.
  • limit (int) – Maximum number of results returned.
  • r (int) – Read quorum needed for the result. Each document is read from at least ‘r’ number of replicas before it is returned in the results.
  • selector (dict) – Dictionary object describing criteria used to select documents.
  • skip (int) – Skip the first ‘n’ results, where ‘n’ is the value specified.
  • sort (list) – A list of fields to sort by. Optionally the list can contain elements that are single member dictionary structures that specify sort direction. For example sort=['name', {'age': 'desc'}] means to sort the query results by the “name” field in ascending order and the “age” field in descending order.
  • use_index (str) – Identifies a specific index for the query to run against, rather than using the Cloudant Query algorithm which finds what it believes to be the best index.
Returns:

Query result data in JSON format
custom_result(**options)

Customizes the QueryResult behavior and provides a convenient context manager for the QueryResult. QueryResult customizations can be made by providing extra options to the query result call using this context manager. The use of skip and limit as options are not valid when using a QueryResult since the skip and limit functionality is handled in the QueryResult.

For example:

with query.custom_result(sort=[{'name': 'asc'}]) as rslt:
    data = rslt[100:200]
Parameters:
  • bookmark (str) – A string that enables you to specify which page of results you require.
  • fields (list) – A list of fields to be returned by the query.
  • page_size (int) – Sets the page size for result iteration. Default is 100.
  • r (int) – Read quorum needed for the result. Each document is read from at least ‘r’ number of replicas before it is returned in the results.
  • selector (dict) – Dictionary object describing criteria used to select documents.
  • sort (list) – A list of fields to sort by. Optionally the list can contain elements that are single member dictionary structures that specify sort direction. For example sort=['name', {'age': 'desc'}] means to sort the query results by the “name” field in ascending order and the “age” field in descending order.
  • use_index (str) – Identifies a specific index for the query to run against, rather than using the Cloudant Query algorithm which finds what it believes to be the best index.
Returns:

Query result data wrapped in a QueryResult instance
url

Constructs and returns the Query URL.

Returns:Query URL