Class AsyncCollectionReference (2.22.0) 

AsyncCollectionReference(*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.

Methods

add

add(
    document_data: dict,
    document_id: typing.Optional[str] = None,
    retry: (
        google.api_core.retry.retry_unary_async.AsyncRetry | object | None
    ) = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> typing.Tuple[typing.Any, typing.Any]

Create a document in the Firestore database with the provided data.

Parameters
Name Description
document_data dict

Property names and values to use for creating the document.
document_id Optional[str]

The document identifier within the current collection. If not provided, an ID will be automatically assigned by the server (the assigned ID will be a random 20 character string composed of digits, uppercase and lowercase letters).
retry google.api_core.retry.Retry

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout float

The timeout for this request. Defaults to a system-specified value.
Exceptions
Type Description
google.cloud.exceptions.Conflict If document_id is provided and the document already exists.
Returns
Type Description
Tuple[google.protobuf.timestamp_pb2.Timestamp, AsyncDocumentReference] Pair of * The update_time when the document was created/overwritten. * A document reference for the created document.

document

document(document_id: str | None = None) -> AsyncDocumentReference

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
AsyncDocumentReference The child document.

get

get(
    transaction: Optional[transaction.Transaction] = None,
    retry: retries.AsyncRetry | object | None = _MethodDefault._DEFAULT_VALUE,
    timeout: Optional[float] = None,
    *,
    explain_options: Optional[ExplainOptions] = None,
    read_time: Optional[datetime.datetime] = None
) -> QueryResultsList[DocumentSnapshot]

Read the documents in this collection.

This sends a RunQuery RPC and returns a list of documents returned in the stream of RunQueryResponse messages.

Parameters
Name Description
retry Optional[google.api_core.retry.Retry]

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout Otional[float]

The timeout for this request. Defaults to a system-specified value.
read_time Optional[datetime.datetime] If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

If set, reads documents as they were at the given time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery is enabled, can additionally be a whole minute timestamp within the past 7 days. If no timezone is specified in the datetime.datetime object, it is assumed to be UTC.
Returns
Type Description
QueryResultsList[DocumentSnapshot] The documents in this collection that match the query.

list_documents

list_documents(
    page_size: int | None = None,
    retry: retries.AsyncRetry | object | None = _MethodDefault._DEFAULT_VALUE,
    timeout: float | None = None,
    *,
    read_time: datetime.datetime | None = None
) -> AsyncGenerator[AsyncDocumentReference, None]

List all subdocuments of the current collection.

Parameters
Name Description
page_size Optional[int]]

The maximum number of documents in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.
retry google.api_core.retry.Retry

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout float

The timeout for this request. Defaults to a system-specified value.
read_time Optional[datetime.datetime]

If set, reads documents as they were at the given time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery is enabled, can additionally be a whole minute timestamp within the past 7 days. If no timezone is specified in the datetime.datetime object, it is assumed to be UTC.
Returns
Type Description
Sequence[DocumentReference] iterator of subdocuments of the current collection. If the collection does not exist at the time of snapshot, the iterator will be empty

stream

stream(
    transaction: Optional[transaction.Transaction] = None,
    retry: retries.AsyncRetry | object | None = _MethodDefault._DEFAULT_VALUE,
    timeout: Optional[float] = None,
    *,
    explain_options: Optional[ExplainOptions] = None,
    read_time: Optional[datetime.datetime] = None
) -> AsyncStreamGenerator[DocumentSnapshot]

Read the documents in this collection.

This sends a RunQuery RPC and then returns a generator which consumes each document returned in the stream of RunQueryResponse messages.

Parameters
Name Description
transaction Optional[ Transaction]

An existing transaction that the query will run in.
retry Optional[google.api_core.retry.Retry]

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout Optional[float]

The timeout for this request. Defaults to a system-specified value.
read_time Optional[datetime.datetime]

If set, reads documents as they were at the given time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery is enabled, can additionally be a whole minute timestamp within the past 7 days. If no timezone is specified in the datetime.datetime object, it is assumed to be UTC.
Returns
Type Description
AsyncStreamGenerator[DocumentSnapshot] A generator of the query results.