Class BaseQuery (2.17.1) 

BaseQuery(
    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.
limit_to_last Optional[bool]

Denotes whether a provided limit is applied to the end of the result set.
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.
recursive Optional[bool]

When true, returns all documents and all documents in any subcollections below them. Defaults to false.

Methods

end_at

end_at(
    document_fields_or_snapshot: typing.Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
) -> google.cloud.firestore_v1.base_query.QueryType

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.

Returns
Type Description
Query A 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: typing.Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
) -> google.cloud.firestore_v1.base_query.QueryType

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.

Returns
Type Description
Query A query with cursor. Acts as a copy of the current query, modified with the newly added "end before" cursor.

limit

limit(count: int) -> google.cloud.firestore_v1.base_query.QueryType

Limit a query to return at most count matching results.

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

Parameter
Name Description
count int

Maximum number of documents to return that match the query.
Returns
Type Description
Query A 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) -> google.cloud.firestore_v1.base_query.QueryType

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.

Parameter
Name Description
count int

Maximum number of documents to return that match the query.
Returns
Type Description
Query A limited query. Acts as a copy of the current query, modified with the newly added "limit" filter.

offset

offset(num_to_skip: int) -> google.cloud.firestore_v1.base_query.QueryType

Skip to an offset in a query.

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

Parameter
Name Description
num_to_skip int

The number of results to skip at the beginning of query results. (Must be non-negative.)
Returns
Type Description
Query An 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"
) -> google.cloud.firestore_v1.base_query.QueryType

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
Name Description
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
Type Description
ValueError If field_path is invalid.
ValueError If direction is not one of ASCENDING or DESCENDING.
Returns
Type Description
Query An ordered query. Acts as a copy of the current query, modified with the newly added "order by" constraint.

recursive

recursive() -> google.cloud.firestore_v1.base_query.QueryType

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: typing.Iterable[str],
) -> google.cloud.firestore_v1.base_query.QueryType

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
Name Description
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
Type Description
ValueError If any field_path is invalid.
Returns
Type Description
Query A "projected" query. Acts as a copy of the current query, modified with the newly added projection.

start_after

start_after(
    document_fields_or_snapshot: typing.Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
) -> google.cloud.firestore_v1.base_query.QueryType

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.

Returns
Type Description
Query A 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: typing.Union[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
) -> google.cloud.firestore_v1.base_query.QueryType

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.

Returns
Type Description
Query A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor.

where

where(
    field_path: typing.Optional[str] = None,
    op_string: typing.Optional[str] = None,
    value=None,
    *,
    filter=None
) -> google.cloud.firestore_v1.base_query.QueryType

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
Name Description
field_path Optional[str]

A field path (.-delimited list of field names) for the field to filter on.
op_string Optional[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
Type Description
ValueError If * field_path is invalid. * If value is a NaN or :data:None and op_string is not ==. * FieldFilter was passed without using the filter keyword argument. * And or Or was passed without using the filter keyword argument . * Both the positional arguments and the keyword argument filter were passed.
Returns
Type Description
Query A filtered query. Acts as a copy of the current query, modified with the newly added filter.