As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Batches

Helpers for batch requests to the Google Cloud Firestore API.

class google.cloud.firestore_v1.base_batch.BaseBatch(client)[source]

Bases: object

Accumulate write operations to be sent in a batch.

This has the same set of methods for write operations that DocumentReference does, e.g. create().

Parameters

client (Client) – The client that created this batch.

abstract commit()[source]

Sends all accumulated write operations to the server. The details of this write depend on the implementing class.

create(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict) → None[source]

Add a “change” to this batch to create a document.

If the document given by reference already exists, then this batch will fail when commit()-ed.

Parameters

  • reference (DocumentReference) – A document reference to be created in this batch.

  • document_data (dict) – Property names and values to use for creating a document.

delete(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = None) → None[source]

Add a “change” to delete a document.

See google.cloud.firestore_v1.document.DocumentReference.delete() for more information on how option determines how the change is applied.

Parameters

  • reference (DocumentReference) – A document reference that will be deleted in this batch.

  • option (Optional[WriteOption]) – A write option to make assertions / preconditions on the server state of the document before applying changes.

set(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict, merge: Union[bool, list] = False) → None[source]

Add a “change” to replace a document.

See google.cloud.firestore_v1.document.DocumentReference.set() for more information on how option determines how the change is applied.

Parameters

  • reference (DocumentReference) – A document reference that will have values set in this batch.

  • document_data (dict) – Property names and values to use for replacing a document.

  • merge (Optional[bool] or Optional[List<apispec>]) – If True, apply merging instead of overwriting the state of the document.

update(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, field_updates: dict, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = None) → None[source]

Add a “change” to update a document.

See google.cloud.firestore_v1.document.DocumentReference.update() for more information on field_updates and option.

Parameters

  • reference (DocumentReference) – A document reference that will be updated in this batch.

  • field_updates (dict) – Field names or paths to update and values to update with.

  • option (Optional[WriteOption]) – A write option to make assertions / preconditions on the server state of the document before applying changes.

class google.cloud.firestore_v1.base_batch.BaseWriteBatch(client)[source]

Bases: google.cloud.firestore_v1.base_batch.BaseBatch

Base class for a/sync implementations of the commit RPC. commit is useful for lower volumes or when the order of write operations is important.

Helpers for batch requests to the Google Cloud Firestore API.

class google.cloud.firestore_v1.batch.WriteBatch(client)[source]

Bases: google.cloud.firestore_v1.base_batch.BaseWriteBatch

Accumulate write operations to be sent in a batch. Use this over BulkWriteBatch for lower volumes or when the order of operations within a given batch is important.

This has the same set of methods for write operations that DocumentReference does, e.g. create().

Parameters

client (Client) – The client that created this batch.

commit(retry: google.api_core.retry.retry_unary.Retry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None) → list[source]

Commit the changes accumulated in this batch.

Parameters

  • 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

The write results corresponding to the changes committed, returned in the same order as the changes were applied to this batch. A write result contains an update_time field.

Return type

List[google.cloud.proto.firestore.v1.write.WriteResult, …]

Helpers for batch requests to the Google Cloud Firestore API.

class google.cloud.firestore_v1.async_batch.AsyncWriteBatch(client)[source]

Bases: google.cloud.firestore_v1.base_batch.BaseWriteBatch

Accumulate write operations to be sent in a batch.

This has the same set of methods for write operations that AsyncDocumentReference does, e.g. create().

Parameters

client (AsyncClient) – The client that created this batch.

async commit(retry: google.api_core.retry.retry_unary_async.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None) → list[source]

Commit the changes accumulated in this batch.

Parameters

  • 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

The write results corresponding to the changes committed, returned in the same order as the changes were applied to this batch. A write result contains an update_time field.

Return type

List[google.cloud.proto.firestore.v1.write.WriteResult, …]