Transactions

Helpers for applying Google Cloud Firestore changes in a transaction.

google.cloud.firestore_v1.transaction.MAX_ATTEMPTS( = )

Default number of transaction attempts (with retries).

• Type

  int

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

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)

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)

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 ] ) – 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)

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]