Class BaseCollectionReference (2.5.2)

Version 2.5.2

• 2.16.0 (latest)
• 2.15.0
• 2.14.0
• 2.13.1
• 2.12.0
• 2.11.1
• 2.10.1
• 2.9.1
• 2.8.0
• 2.7.3
• 2.6.1
• 2.5.3
• 2.4.0
• 2.3.4
• 2.2.0
• 2.1.3
• 2.0.2
• 1.9.2
• 1.8.1
• 1.7.0
• 1.6.2
• 1.5.0
• 1.4.0
• 1.3.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.

Inheritance

builtins.object > BaseCollectionReference

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

document

document(document_id: Optional[str] = None)

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[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

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[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

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.

limit

limit(count: int)

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)

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)

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

See xref_order_by for more information on this method.

Parameters

Name	Description
field_path	str A field path (.-delimited list of field names) on which to order the query results.
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.

Returns

Type	Description
Query	An "order by" query.

select

select(field_paths: Iterable[str])

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[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

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[
        google.cloud.firestore_v1.base_document.DocumentSnapshot, dict, list, tuple
    ]
)

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.

where

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

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.
op_string	str A comparison operation in the form of a string. Acceptable values are <, <=, ==, >=, >, and in.
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.

Returns

Type	Description
Query	A filtered query.