Class CollectionReference

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.

Inheritance

builtins.object > BaseCollectionReference > CollectionReference

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
NameDescription
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
TypeDescription
ConflictIf ``document_id`` is provided and the document already exists.
Returns
TypeDescription
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
NameDescription
transaction

(Optional[Transaction]): An existing transaction that this 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 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
TypeDescription
listThe 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
NameDescription
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
TypeDescription
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
NameDescription
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.

.. 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.

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).

Parameters
NameDescription
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.