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.
Parameters
parent (
CollectionReference
) – The collection that this query applies to.
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 isTrue
, 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 byorders
.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 isTrue
, 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 byorders
.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 atransaction
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
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.