Class Query (2.18.0) 

Query(
    parent,
    projection=None,
    field_filters=(),
    orders=(),
    limit=None,
    limit_to_last=False,
    offset=None,
    start_at=None,
    end_at=None,
    all_descendants=False,
    recursive=False,
)

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
Name Description
parent CollectionReference

The collection that this query applies to.
projection Optional[Projection]

A projection of document fields to limit the query results to.
field_filters Optional[Tuple[FieldFilter, ...]]

The filters to be applied in the query.
orders Optional[Tuple[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]]

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 :data: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]]

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 :data: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.

Methods

avg

avg(
    field_ref: str | FieldPath, alias: str | None = None
) -> Type["firestore_v1.aggregation.AggregationQuery"]

Adds an avg over the query.

Parameters
Name Description
field_ref [Union[str, google.cloud.firestore_v1.field_path.FieldPath]

The field to aggregate across.
alias Optional[str]

Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_<incremental_id++>.

count

count(
    alias: typing.Optional[str] = None,
) -> typing.Type[google.cloud.firestore_v1.aggregation.AggregationQuery]

Adds a count over the query.

Parameter
Name Description
alias Optional[str]

Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_<incremental_id++>.

find_nearest

find_nearest(
    vector_field: str,
    query_vector: google.cloud.firestore_v1.vector.Vector,
    limit: int,
    distance_measure: google.cloud.firestore_v1.base_vector_query.DistanceMeasure,
    *,
    distance_result_field: typing.Optional[str] = None,
    distance_threshold: typing.Optional[float] = None
) -> typing.Type[google.cloud.firestore_v1.vector_query.VectorQuery]

Finds the closest vector embeddings to the given query vector.

Parameters
Name Description
vector_field str

An indexed vector field to search upon. Only documents which contain vectors whose dimensionality match the query_vector can be returned.
query_vector Vector

The query vector that we are searching on. Must be a vector of no more than 2048 dimensions.
limit int

The number of nearest neighbors to return. Must be a positive integer of no more than 1000.
distance_measure DistanceMeasure

The Distance Measure to use.
distance_result_field Optional[str]

Name of the field to output the result of the vector distance calculation. If unset then the distance will not be returned.
distance_threshold Optional[float]

A threshold for which no less similar documents will be returned.

get

get(
    transaction=None,
    retry: google.api_core.retry.retry_unary.Retry = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> typing.List[google.cloud.firestore_v1.base_document.DocumentSnapshot]

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
Name Description
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
Type Description
list The documents in the collection that match this query.

on_snapshot

on_snapshot(callback: typing.Callable) -> google.cloud.firestore_v1.watch.Watch

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
Name Description
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: typing.Optional[
        google.cloud.firestore_v1.transaction.Transaction
    ] = None,
    retry: typing.Optional[
        google.api_core.retry.retry_unary.Retry
    ] = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> google.cloud.firestore_v1.stream_generator.StreamGenerator[
    google.cloud.firestore_v1.base_document.DocumentSnapshot
]

Read the documents in the collection that match this query.

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

Parameters
Name Description
retry Optional[google.api_core.retry.Retry]

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout Optinal[float]

The timeout for this request. Defaults
Returns
Type Description
StreamGenerator[DocumentSnapshot] A generator of the query results.

sum

sum(
    field_ref: str | FieldPath, alias: str | None = None
) -> Type["firestore_v1.aggregation.AggregationQuery"]

Adds a sum over the query.

Parameters
Name Description
field_ref Union[str, google.cloud.firestore_v1.field_path.FieldPath]

The field to aggregate across.
alias Optional[str]

Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_<incremental_id++>.