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
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
google.cloud.firestore_v1.base_transaction.MAX_ATTEMPTS( = )
Default number of transaction attempts (with retries).
Type
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_unary.Retry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
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_unary.Retry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
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_unary.Retry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
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
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_unary_async.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
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_unary_async.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
Retrieve a document or a query result from the database.
Parameters
return. (ref_or_query The document references* or *query object to) –
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_unary_async.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None)
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
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]