Class Transaction (2.18.0)

Transaction(client, max_attempts=5, read_only=False)

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

Parameters
Name	Description
`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 :data:`False`.

Properties

id

Get the current transaction ID.

Returns
Type	Description
`Optional[bytes]`	The transaction ID (or :data:`None` if the current transaction is not in progress).

in_progress

Determine if this transaction has already begun.

Returns
Type	Description
`bool`	Indicates if the transaction has started.

Methods

commit

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

Commit the changes accumulated in this batch.

Parameters
Name	Description
`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
Type	Description
`List[WriteResult, ...]`	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.

create

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

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
Name	Description
`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

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

Add a "change" to delete a document.

See xref_delete for more information on how option determines how the change is applied.

Parameters
Name	Description
`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

get(
    ref_or_query,
    retry: google.api_core.retry.retry_unary.Retry = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> typing.Generator[
    google.cloud.firestore_v1.base_document.DocumentSnapshot, typing.Any, None
]

Retrieve a document or a query result from the database.

Parameters
Name	Description
`retry`	`google.api_core.retry.Retry` Designation of what errors, if any, should be retried. Defaults to a system-specified policy.
`timeout`	`float :Yields: .DocumentSnapshot -- The next document snapshot that fulfills the query, or :data:None if the document does not exist.` The timeout for this request. Defaults to a system-specified value.

get_all

get_all(
    references: list,
    retry: google.api_core.retry.retry_unary.Retry = _MethodDefault._DEFAULT_VALUE,
    timeout: typing.Optional[float] = None,
) -> typing.Generator[
    google.cloud.firestore_v1.base_document.DocumentSnapshot, typing.Any, None
]

Retrieves multiple documents from Firestore.

Parameters
Name	Description
`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 :Yields: .DocumentSnapshot -- The next document snapshot that fulfills the query, or :data:None if the document does not exist.` The timeout for this request. Defaults to a system-specified value.

set

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

Add a "change" to replace a document.

See xref_set for more information on how option determines how the change is applied.

Parameters
Name	Description
`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

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

Add a "change" to update a document.

See xref_update for more information on field_updates and option.

Parameters
Name	Description
`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.