Class BaseCollectionReference (2.16.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
Name	Description
`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
Type	Description
`str`	The last component of the path.

parent

Document that owns the current collection.

Returns
Type	Description
`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
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=None)

Adds a count over the nested query.

Parameter
Name	Description
`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
Name	Description
`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
Type	Description
`DocumentReference`	The 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
Name	Description
`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
Type	Description
`Query`	A 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
Name	Description
`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
Type	Description
`Query`	A query with cursor.

find_nearest

find_nearest(
    vector_field: str,
    query_vector: Vector,
    limit: int,
    distance_measure: DistanceMeasure,
) -> 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.

limit

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

Create a limited query with this collection as parent.

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

See xref_limit for more information on this method.

Parameter
Name	Description
`count`	`int` Maximum number of documents to return that match the query.

Returns
Type	Description
`Query`	A limited query.

limit_to_last

limit_to_last(count: int)

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

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

See xref_limit_to_last for more information on this method.

Parameter
Name	Description
`count`	`int` Maximum number of documents to return that match the query.

Returns
Type	Description
`Query`	A 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
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.

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
Name	Description
`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
Type	Description
`Query`	An "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
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.

Returns
Type	Description
`Query`	A "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
Name	Description
`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
Type	Description
`Query`	A 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
Name	Description
`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
Type	Description
`Query`	A query with cursor.

sum

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

Adds a sum over the nested 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++>.

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
Name	Description
`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
Type	Description
`ValueError`	if both the positional arguments (field_path, op_string, value): and the filter keyword argument are passed at the same time.

Returns
Type	Description
`Query`	A filtered query.

Class BaseCollectionReference (2.16.0)

Parameters

Properties

id

parent

Methods

avg

count

document

end_at

end_before

find_nearest

limit

limit_to_last

offset

order_by

select

start_after

start_at

sum

where