On January 1, 2020 this library will no longer support Python 2 on the latest released version. Previously released library versions will continue to be available. For more information please visit Python 2 support on Google Cloud.

Transactions

Helpers for applying Google Cloud Firestore changes in a transaction.

google.cloud.firestore_v1.transaction.MAX_ATTEMPTS = 5

Default number of transaction attempts (with retries).

Type

int

class google.cloud.firestore_v1.transaction.Transaction(client, max_attempts=5, read_only=False)[source]

Bases: google.cloud.firestore_v1.batch.WriteBatch

Accumulate read-and-write operations to be sent in a transaction.

Parameters
  • client (Client) – The client that created this transaction.

  • max_attempts (Optional[int]) – The maximum number of attempts for the transaction (i.e. allowing retries). Defaults to MAX_ATTEMPTS.

  • read_only (Optional[bool]) – Flag indicating if the transaction should be read-only or should allow writes. Defaults to False.

commit()

Commit the changes accumulated in this batch.

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_pb2.WriteResult, …]

create(reference, document_data)

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, option=None)

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.

get(ref_or_query)[source]

Retrieve a document or a query result from the database. :param ref_or_query The document references or query object to return.:

Yields

.DocumentSnapshot – The next document snapshot that fulfills the query, or None if the document does not exist.

get_all(references)[source]

Retrieves multiple documents from Firestore.

Parameters

references (List[DocumentReference, ..]) – Iterable of document references to be retrieved.

Yields

.DocumentSnapshot – The next document snapshot that fulfills the query, or None if the document does not exist.

property id

Get the current transaction ID.

Returns

The transaction ID (or None if the current transaction is not in progress).

Return type

Optional[bytes]

property in_progress

Determine if this transaction has already begun.

Returns

Indicates if the transaction has started.

Return type

bool

set(reference, document_data, merge=False)

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, field_updates, option=None)

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.

google.cloud.firestore_v1.transaction.transactional(to_wrap)[source]

Decorate a callable so that it runs in a transaction.

Parameters

to_wrap – (Callable[[Transaction, …], Any]): A callable that should be run (and retried) in a transaction.

Returns

the wrapped callable.

Return type

Callable[[Transaction, …], Any]