Class BaseCollectionReference (2.14.0)

BaseCollectionReference(*path, **kwargs)

A reference to a collection in a Firestore database.

The collection may already exist or this class can facilitate creation of documents within the collection.

Parameters

NameDescription
path Tuple[str, ...]

The components in the collection path. This is a series of strings representing each collection and sub-collection ID, as well as the document IDs for any documents that contain a sub-collection.

kwargs dict

The keyword arguments for the constructor. The only supported keyword is client and it must be a Client if provided. It represents the client that created this collection reference.

Properties

id

The collection identifier.

Returns
TypeDescription
strThe last component of the path.

parent

Document that owns the current collection.

Returns
TypeDescription
Optional[DocumentReference]The parent document, if the current collection is not a top-level collection.

Methods

avg

avg(field_ref: str | FieldPath, alias=None)

Adds an avg over the nested query.

Parameters
NameDescription
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=None)

Adds a count over the nested query.

Parameter
NameDescription
alias str

(Optional) The alias for the count

document

document(
    document_id: typing.Optional[str] = None,
) -> google.cloud.firestore_v1.document.DocumentReference

Create a sub-document underneath the current collection.

Parameter
NameDescription
document_id Optional[str]

The document identifier within the current collection. If not provided, will default to a random 20 character string composed of digits, uppercase and lowercase and letters.

Returns
TypeDescription
DocumentReferenceThe child document.

end_at

end_at(document_fields: Union[DocumentSnapshot, dict, list, tuple]) -> QueryType

End query at a cursor with this collection as parent.

See xref_end_at for more information on this method.

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

end_before

end_before(
    document_fields: Union[DocumentSnapshot, dict, list, tuple]
) -> QueryType

End query before a cursor with this collection as parent.

See xref_end_before for more information on this method.

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

limit

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

Create a limited query with this collection as parent.

See xref_limit for more information on this method.

Parameter
NameDescription
count int

Maximum number of documents to return that match the query.

Returns
TypeDescription
QueryA limited query.

limit_to_last

limit_to_last(count: int)

Create a limited to last query with this collection as parent.

See xref_limit_to_last for more information on this method.

Parameter
NameDescription
count int

Maximum number of documents to return that match the query.

Returns
TypeDescription
QueryA limited to last query.

offset

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

Skip to an offset in a query with this collection as parent.

See xref_offset for more information on this method.

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.

order_by

order_by(
    field_path: str, **kwargs
) -> google.cloud.firestore_v1.base_query.QueryType

Create an "order by" query with this collection as parent.

See xref_order_by for more information on this method.

Parameters
NameDescription
kwargs Dict[str, Any]

The keyword arguments to pass along to the query. The only supported keyword is direction, see order_by for more information.

field_path str

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

Returns
TypeDescription
QueryAn "order by" query.

select

select(
    field_paths: typing.Iterable[str],
) -> google.cloud.firestore_v1.base_query.QueryType

Create a "select" query with this collection as parent.

See xref_select for more information on this method.

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.

Returns
TypeDescription
QueryA "projected" query.

start_after

start_after(
    document_fields: Union[DocumentSnapshot, dict, list, tuple]
) -> QueryType

Start query after a cursor with this collection as parent.

See xref_start_after for more information on this method.

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

start_at

start_at(document_fields: Union[DocumentSnapshot, dict, list, tuple]) -> QueryType

Start query at a cursor with this collection as parent.

See xref_start_at for more information on this method.

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

sum

sum(field_ref: str | FieldPath, alias=None)

Adds a sum over the nested query.

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

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

Create a "where" query with this collection as parent.

See xref_where for more information on this method.

Parameters
NameDescription
field_path str

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

op_string str

A comparison operation in the form of a string. Acceptable values are <, <=, ==, >=, >, and in. Optional.

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. If op_string is in, value must be a sequence of values. Optional.

Exceptions
TypeDescription
ValueErrorif both the positional arguments (field_path, op_string, value): and the filter keyword argument are passed at the same time.
Returns
TypeDescription
QueryA filtered query.