Class AsyncCollectionReference (2.17.0)

Version 2.17.0

• 2.19.0 (latest)
• 2.18.0
• 2.17.2
• 2.16.1
• 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

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 = _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: typing.Optional[str] = None,
) -> google.cloud.firestore_v1.async_document.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: typing.Optional[
        google.cloud.firestore_v1.transaction.Transaction
    ] = None,
    retry: typing.Optional[
        google.api_core.retry.retry_unary_async.AsyncRetry
    ] = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> list

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
transaction	typing.Optional[google.cloud.firestore_v1.transaction.Transaction] (Optional[Transaction]): An existing transaction that this 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	Otional[float] 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). The timeout for this request. Defaults to a system-specified value.

Returns
Type	Description
list	The documents in this collection that match the query.

list_documents

list_documents(
    page_size: typing.Optional[int] = None,
    retry: google.api_core.retry.retry_unary_async.AsyncRetry = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> typing.AsyncGenerator[google.cloud.firestore_v1.document.DocumentReference, 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.

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: typing.Optional[
        google.cloud.firestore_v1.transaction.Transaction
    ] = None,
    retry: typing.Optional[
        google.api_core.retry.retry_unary_async.AsyncRetry
    ] = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = 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.

Note: The underlying stream of responses will time out after the max_rpc_timeout_millis value set in the GAPIC client configuration for the RunQuery API. Snapshots not consumed from the iterator before that point will be lost.

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.

Returns
Type	Description
AsyncStreamGenerator[DocumentSnapshot]	A generator of the query results.