As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date 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.

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

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 = 5

Default number of transaction attempts (with retries).

Type

int

Helpers for applying Google Cloud Firestore changes in a transaction.

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

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) → list

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) → 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

  • 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) → 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: DocumentReference | Query, retry: retries.Retry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None, *, explain_options: Optional[ExplainOptions] = None) → StreamGenerator[DocumentSnapshot] | Generator[DocumentSnapshot, Any, None][source]

Retrieve a document or a query result from the database.

Parameters

  • ref_or_query (DocumentReference | 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.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. Can only be used when running a query, not a document reference.

Yields

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

Raises

  • ValueError – if ref_or_query is not one of the supported types, or

  • explain_options is provided when ref_or_query is a document –

  • reference. –

get_all(references: list, retry: retries.Retry = _MethodDefault._DEFAULT_VALUE, timeout: float = None) → Generator[DocumentSnapshot, Any, None][source]

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) → None

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: google.cloud.firestore_v1.base_document.BaseDocumentReference, field_updates: dict, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = None) → 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) → google.cloud.firestore_v1.transaction._Transactional[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]

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)[source]

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) → list

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) → 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

  • 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) → 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: AsyncDocumentReference | AsyncQuery, retry: retries.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: Optional[float] = None, *, explain_options: Optional[ExplainOptions] = None) → AsyncGenerator[DocumentSnapshot, Any] | AsyncStreamGenerator[DocumentSnapshot][source]

Retrieve a document or a query result from the database.

Parameters

  • ref_or_query (AsyncDocumentReference | AsyncQuery) – 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.

  • explain_options – (Optional[ExplainOptions]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. Can only be used when running a query, not a document reference.

Yields

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

Raises

  • ValueError – if ref_or_query is not one of the supported types, or

  • explain_options is provided when ref_or_query is a document –

  • reference. –

async get_all(references: list, retry: retries.AsyncRetry = _MethodDefault._DEFAULT_VALUE, timeout: float = None) → AsyncGenerator[DocumentSnapshot, Any][source]

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) → None

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: google.cloud.firestore_v1.base_document.BaseDocumentReference, field_updates: dict, option: Optional[google.cloud.firestore_v1._helpers.WriteOption] = None) → 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]) → google.cloud.firestore_v1.async_transaction._AsyncTransactional[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]