Collections

Classes for representing collections for the Google Cloud Firestore API.

class google.cloud.firestore_v1.collection.CollectionReference(*path, **kwargs)

Bases: google.cloud.firestore_v1.base_collection.BaseCollectionReference

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

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

• Raises

  • ValueError – if

    * the path is empty * there are an even number of elements * a collection ID in path is not a string * a document ID in path is not a string

  • TypeError – If a keyword other than client is used.

add(document_data: dict, document_id: Optional[str] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

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

• Parameters

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

• Returns

  Pair of

  • The update_time when the document was created/overwritten.

  • A document reference for the created document.

• Return type

  Tuple[ google.protobuf.timestamp_pb2.Timestamp , DocumentReference ]

• Raises

  Conflict– If document_id is provided and the document already exists.

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

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

  • 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 ) – The timeout for this request. Defaults to a system-specified value.

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

• Returns

  The documents in this collection that match the query.

• Return type

  list

list_documents(page_size: Optional[int] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

List all subdocuments of the current collection.

• Parameters

  • 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

  iterator of subdocuments of the current collection. If the collection does not exist at the time of snapshot, the iterator will be empty

• Return type

  Sequence[ DocumentReference ]

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.

• Parameters

  callback(Callable[[ CollectionSnapshot ], NoneType]) – a callback to run when a change occurs.

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

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

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

  • 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 ) – The timeout for this request. Defaults to a system-specified value.

• Yields

  DocumentSnapshot – The next document that fulfills the query.