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 aClient
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 inpath
is not a string * a document ID inpath
is not a stringTypeError – 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_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.