Class CollectionReference (2.10.1) 

CollectionReference(*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: Optional[str] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)

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, DocumentReference] Pair of * The update_time when the document was created/overwritten. * A document reference for the created document.

get

get(transaction: Optional[google.cloud.firestore_v1.transaction.Transaction] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)

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 google.api_core.retry.Retry

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout 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: Optional[int] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = 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

on_snapshot

on_snapshot(callback: Callable)

Monitor the documents in this collection.

This starts a watch on this collection using a background thread. The provided callback is run on the snapshot of the documents.

Parameter
Name Description
callback Callable[[CollectionSnapshot], NoneType] .. rubric:: Example from google.cloud import firestore_v1 db = firestore_v1.Client() collection_ref = db.collection(u'users') def on_snapshot(collection_snapshot, changes, read_time): for doc in collection_snapshot.documents: print(u'{} => {}'.format(doc.id, doc.to_dict())) # Watch this collection collection_watch = collection_ref.on_snapshot(on_snapshot) # Terminate this watch collection_watch.unsubscribe()

a callback to run when a change occurs.

stream

stream(transaction: Optional[google.cloud.firestore_v1.transaction.Transaction] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)

Read the documents in this collection.

This sends a RunQuery RPC and then returns an iterator 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 google.api_core.retry.Retry

Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
timeout float :Yields: DocumentSnapshot -- The next document that fulfills the query.

The timeout for this request. Defaults to a system-specified value.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月10日 UTC.