Queries

Classes for representing queries for the Google Cloud Firestore API.

A Query can be created directly from a Collection and that can be a more common way to create a query than direct usage of the constructor.

class google.cloud.firestore_v1.query.CollectionGroup(parent, projection=None, field_filters=(), orders=(), limit=None, limit_to_last=False, offset=None, start_at=None, end_at=None, all_descendants=True)

Bases: google.cloud.firestore_v1.query.Query, google.cloud.firestore_v1.base_query.BaseCollectionGroup

Represents a Collection Group in the Firestore API.

This is a specialization of Query that includes all documents in the database that are contained in a collection or subcollection of the given parent.

get_partitions(partition_count, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Partition a query for parallelization.

Partitions a query by returning partition cursors that can be used to run the query in parallel. The returned partition cursors are split points that can be used as starting/end points for the query results.

  • Parameters

    • partition_count (int) – The desired maximum number of partition points. The number must be strictly positive. The actual number of partitions returned may be fewer.

    • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

    • timeout (float) – The timeout for this request. Defaults to a system-specified value.

class google.cloud.firestore_v1.query.Query(parent, projection=None, field_filters=(), orders=(), limit=None, limit_to_last=False, offset=None, start_at=None, end_at=None, all_descendants=False)

Bases: google.cloud.firestore_v1.base_query.BaseQuery

Represents a query to the Firestore API.

Instances of this class are considered immutable: all methods that would modify an instance instead return a new instance.

  • Parameters

    • parent (CollectionReference) – The collection that this query applies to.

    • projection (Optional[google.cloud.proto.firestore.v1. query.StructuredQuery.Projection]) – A projection of document fields to limit the query results to.

    • field_filters (Optional[Tuple[google.cloud.proto.firestore.v1. query.StructuredQuery.FieldFilter, …]]) – The filters to be applied in the query.

    • orders (Optional[Tuple[google.cloud.proto.firestore.v1. query.StructuredQuery.Order, …]]) – The “order by” entries to use in the query.

    • limit (Optional[int]) – The maximum number of documents the query is allowed to return.

    • offset (Optional[int]) – The number of results to skip.

    • start_at (Optional[Tuple[dict, *[bool](https://python.readthedocs.io/en/latest/library/functions.html#bool)]*]) – Two-tuple of :

      • a mapping of fields. Any field that is present in this mapping must also be present in orders

      • an after flag

      The fields and the flag combine to form a cursor used as a starting point in a query result set. If the after flag is True, the results will start just after any documents which have fields matching the cursor, otherwise any matching documents will be included in the result set. When the query is formed, the document values will be used in the order given by orders.

    • end_at (Optional[Tuple[dict, *[bool](https://python.readthedocs.io/en/latest/library/functions.html#bool)]*]) – Two-tuple of:

      • a mapping of fields. Any field that is present in this mapping must also be present in orders

      • a before flag

      The fields and the flag combine to form a cursor used as an ending point in a query result set. If the before flag is True, the results will end just before any documents which have fields matching the cursor, otherwise any matching documents will be included in the result set. When the query is formed, the document values will be used in the order given by orders.

    • all_descendants (Optional[bool]) – When false, selects only collections that are immediate children of the parent specified in the containing RunQueryRequest. When true, selects all descendant collections.

get(transaction=None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Read the documents in the collection that match this query.

This sends a RunQuery RPC and returns a list of documents returned in the stream of RunQueryResponse messages.

  • Parameters

    • transaction – (Optional[Transaction]): An existing transaction that this query will run in. If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

    • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

    • timeout (float) – The timeout for this request. Defaults to a system-specified value.

  • Returns

    The documents in the collection that match this query.

  • Return type

    list

on_snapshot(callback: Callable)

Monitor the documents in this collection that match this query.

This starts a watch on this query using a background thread. The provided callback is run on the snapshot of the documents.

  • Parameters

    callback (Callable[[QuerySnapshot], NoneType]) – a callback to run when a change occurs.

Example:

from google.cloud import firestore_v1

db = firestore_v1.Client()
query_ref = db.collection(u'users').where("user", "==", u'Ada')

def on_snapshot(docs, changes, read_time):
    for doc in docs:
        print(u'{} => {}'.format(doc.id, doc.to_dict()))

# Watch this query
query_watch = query_ref.on_snapshot(on_snapshot)

# Terminate this watch
query_watch.unsubscribe()

stream(transaction=None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Read the documents in the collection that match this query.

This sends a RunQuery RPC and then returns an iterator which consumes each document returned in the stream of RunQueryResponse messages.

NOTE: The underlying stream of responses will time out after the max_rpc_timeout_millis value set in the GAPIC client configuration for the RunQuery API. Snapshots not consumed from the iterator before that point will be lost.

If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

  • Parameters

    • transaction – (Optional[Transaction]): An existing transaction that this query will run in.

    • retry (google.api_core.retry.Retry) – Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

    • timeout (float) – The timeout for this request. Defaults to a system-specified value.

  • Yields

    DocumentSnapshot – The next document that fulfills the query.