Transactions

Helpers for applying Google Cloud Firestore changes in a transaction.

class google.cloud.firestore_v1.base_transaction.BaseTransaction(max_attempts=5, read_only=False)

Bases: object

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

  • Parameters

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

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

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

Default number of transaction attempts (with retries).

Helpers for applying Google Cloud Firestore changes in a transaction.

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

Bases: google.cloud.firestore_v1.batch.WriteBatch, google.cloud.firestore_v1.base_transaction.BaseTransaction

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(retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

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, โ€ฆ]

create(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict)

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)

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, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Retrieve a document or a query result from the database.

  • Parameters

    • ref_or_query โ€“ The document references or query object to return.

    • 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 snapshot that fulfills the query, or None if the document does not exist.

get_all(references: list, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Retrieves multiple documents from Firestore.

  • Parameters

    • references (List[DocumentReference, **...]) โ€“ Iterable of document references to be retrieved.

    • 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 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: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict, merge: Union[bool, list] = 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: google.cloud.firestore_v1.base_document.BaseDocumentReference, field_updates: dict, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = 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: Callable)

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]

Helpers for applying Google Cloud Firestore changes in a transaction.

class google.cloud.firestore_v1.async_transaction.AsyncTransaction(client, max_attempts=5, read_only=False)

Bases: google.cloud.firestore_v1.async_batch.AsyncWriteBatch, google.cloud.firestore_v1.base_transaction.BaseTransaction

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.

async commit(retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

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, โ€ฆ]

create(reference: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict)

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)

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.

async get(ref_or_query, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Retrieve a document or a query result from the database.

  • Parameters

    • The document references** or ***query object to return.* (ref_or_query) โ€“

    • 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 snapshot that fulfills the query, or None if the document does not exist.

async get_all(references: list, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Retrieves multiple documents from Firestore.

  • Parameters

    • references (List[AsyncDocumentReference, **...]) โ€“ Iterable of document references to be retrieved.

    • 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 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: google.cloud.firestore_v1.base_document.BaseDocumentReference, document_data: dict, merge: Union[bool, list] = 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: google.cloud.firestore_v1.base_document.BaseDocumentReference, field_updates: dict, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = 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.async_transaction.async_transactional(to_wrap: Callable[[google.cloud.firestore_v1.async_transaction.AsyncTransaction], Any])

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]