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

Inheritance

builtins.object > BaseQuery

Methods

end_at

end_at(
    document_fields_or_snapshot: Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

End query results at a particular document value.

The result set will include the document specified by document_fields_or_snapshot.

If the current query already has specified an end cursor -- either via this method or xref_end_before -- this will overwrite it.

When the query is sent to the server, the document_fields_or_snapshot will be used in the order given by fields set by xref_order_by.

Parameter
NameDescription
document_fields_or_snapshot

(Union[DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set.

Returns
TypeDescription
QueryA query with cursor. Acts as a copy of the current query, modified with the newly added "end at" cursor.

end_before

end_before(
    document_fields_or_snapshot: Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

End query results before a particular document value.

The result set will exclude the document specified by document_fields_or_snapshot.

If the current query already has specified an end cursor -- either via this method or xref_end_at -- this will overwrite it.

When the query is sent to the server, the document_fields_or_snapshot will be used in the order given by fields set by xref_order_by.

Parameter
NameDescription
document_fields_or_snapshot

(Union[DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set.

Returns
TypeDescription
QueryA query with cursor. Acts as a copy of the current query, modified with the newly added "end before" cursor.

limit

limit(count: int)

Limit a query to return at most count matching results.

If the current query already has a limit set, this will override it.

.. note:: limit and limit_to_last are mutually exclusive. Setting limit will drop previously set limit_to_last.

Parameter
NameDescription
count int

Maximum number of documents to return that match the query.

Returns
TypeDescription
QueryA limited query. Acts as a copy of the current query, modified with the newly added "limit" filter.

limit_to_last

limit_to_last(count: int)

Limit a query to return the last count matching results. If the current query already has a limit_to_last set, this will override it.

.. note:: limit and limit_to_last are mutually exclusive. Setting limit_to_last will drop previously set limit.

Parameter
NameDescription
count int

Maximum number of documents to return that match the query.

Returns
TypeDescription
QueryA limited query. Acts as a copy of the current query, modified with the newly added "limit" filter.

offset

offset(num_to_skip: int)

Skip to an offset in a query.

If the current query already has specified an offset, this will overwrite it.

Parameter
NameDescription
num_to_skip int

The number of results to skip at the beginning of query results. (Must be non-negative.)

Returns
TypeDescription
QueryAn offset query. Acts as a copy of the current query, modified with the newly added "offset" field.

order_by

order_by(field_path: str, direction: str = "ASCENDING")

Modify the query to add an order clause on a specific field.

See xref_field_path for more information on field paths.

Successive xref_order_by calls will further refine the ordering of results returned by the query (i.e. the new "order by" fields will be added to existing ones).

Parameters
NameDescription
field_path str

A field path (.-delimited list of field names) on which to order the query results.

direction Optional[str]

The direction to order by. Must be one of ASCENDING or DESCENDING, defaults to ASCENDING.

Exceptions
TypeDescription
ValueErrorIf ``field_path`` is invalid.
ValueErrorIf ``direction`` is not one of `ASCENDING` or `DESCENDING`.
Returns
TypeDescription
QueryAn ordered query. Acts as a copy of the current query, modified with the newly added "order by" constraint.

recursive

recursive()

Returns a copy of this query whose iterator will yield all matching documents as well as each of their descendent subcollections and documents.

This differs from the all_descendents flag, which only returns descendents whose subcollection names match the parent collection's name. To return all descendents, regardless of their subcollection name, use this.

select

select(field_paths: Iterable[str])

Project documents matching query to a limited set of fields.

See xref_field_path for more information on field paths.

If the current query already has a projection set (i.e. has already called xref_select), this will overwrite it.

Parameter
NameDescription
field_paths Iterable[str, ...]

An iterable of field paths (.-delimited list of field names) to use as a projection of document fields in the query results.

Exceptions
TypeDescription
ValueErrorIf any ``field_path`` is invalid.
Returns
TypeDescription
QueryA "projected" query. Acts as a copy of the current query, modified with the newly added projection.

start_after

start_after(
    document_fields_or_snapshot: Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

Start query results after a particular document value.

The result set will exclude the document specified by document_fields_or_snapshot.

If the current query already has specified a start cursor -- either via this method or xref_start_at -- this will overwrite it.

When the query is sent to the server, the document_fields_or_snapshot will be used in the order given by fields set by xref_order_by.

Parameter
NameDescription
document_fields_or_snapshot

(Union[DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set.

Returns
TypeDescription
QueryA query with cursor. Acts as a copy of the current query, modified with the newly added "start after" cursor.

start_at

start_at(
    document_fields_or_snapshot: Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

Start query results at a particular document value.

The result set will include the document specified by document_fields_or_snapshot.

If the current query already has specified a start cursor -- either via this method or xref_start_after -- this will overwrite it.

When the query is sent to the server, the document_fields will be used in the order given by fields set by xref_order_by.

Parameter
NameDescription
document_fields_or_snapshot

(Union[DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set.

Returns
TypeDescription
QueryA query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor.

where

where(field_path: str, op_string: str, value)

Filter the query on a field.

See xref_field_path for more information on field paths.

Returns a new xref_Query that filters on a specific field path, according to an operation (e.g. == or "equals") and a particular value to be paired with that operation.

Parameters
NameDescription
field_path str

A field path (.-delimited list of field names) for the field to filter on.

op_string str

A comparison operation in the form of a string. Acceptable values are <, <=, ==, !=, >=, >, in, not-in, array_contains and array_contains_any.

value Any

The value to compare the field against in the filter. If value is :data:None or a NaN, then == is the only allowed operation.

Exceptions
TypeDescription
ValueErrorIf ``field_path`` is invalid.
ValueErrorIf ``value`` is a NaN or :data:`None` and ``op_string`` is not ``==``.
Returns
TypeDescription
QueryA filtered query. Acts as a copy of the current query, modified with the newly added filter.