Class Query

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.

Inheritance

builtins.object > BaseQuery > Query

Methods

get

get(transaction=None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)

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
NameDescription
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.

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).

Returns
TypeDescription
listThe documents in the collection that match this query.

on_snapshot

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.

Parameter
NameDescription
callback Callable[[QuerySnapshot], NoneType] Example: .. code-block:: python 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()

a callback to run when a change occurs.

stream

stream(transaction=None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)

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
NameDescription
retry google.api_core.retry.Retry

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.

timeout float :Yields: *DocumentSnapshot* -- The next document that fulfills the query.

The timeout for this request. Defaults to a system-specified value.

transaction

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