Client

Client for interacting with the Google Cloud Firestore API.

This is the base from which all interactions with the API occur.

In the hierarchy of API concepts

class google.cloud.firestore_v1.client.Client(project=None, credentials=None, database='(default)', client_info=<google.api_core.gapic_v1.client_info.ClientInfo object>, client_options=None)

Bases: google.cloud.firestore_v1.base_client.BaseClient

Client for interacting with Google Cloud Firestore API.

NOTE: Since the Cloud Firestore API requires the gRPC transport, no _http argument is accepted by this class.

  • Parameters

    • project (Optional[str]) – The project which the client acts on behalf of. If not passed, falls back to the default inferred from the environment.

    • credentials (Optional[Credentials]) – The OAuth2 Credentials to use for this client. If not passed, falls back to the default inferred from the environment.

    • database (Optional[str]) – The database name that the client targets. For now, DEFAULT_DATABASE (the default value) is the only valid database.

    • client_info (Optional[google.api_core.gapic_v1.client_info.ClientInfo]) – The client info used to send a user-agent string along with API requests. If None, then default info will be used. Generally, you only need to set this if you’re developing your own library or partner tool.

    • client_options (Union[dict, *[google.api_core.client_options.ClientOptions](https://googleapis.dev/python/google-api-core/latest/client_options.html#google.api_core.client_options.ClientOptions)]*) – Client options used to set user options on the client. API Endpoint should be set through client_options.

batch()

Get a batch instance from this client.

  • Returns

    A “write” batch to be used for accumulating document changes and sending the changes all at once.

  • Return type

    WriteBatch

collection(*collection_path: Tuple[str])

Get a reference to a collection.

For a top-level collection:

>>> client.collection('top')

For a sub-collection:

>>> client.collection('mydocs/doc/subcol')
>>> # is the same as
>>> client.collection('mydocs', 'doc', 'subcol')

Sub-collections can be nested deeper in a similar fashion.

  • Parameters

    collection_path (Tuple[str, **...]) – Can either be

    • A single /-delimited path to a collection

    • A tuple of collection path segments

  • Returns

    A reference to a collection in the Firestore database.

  • Return type

    CollectionReference

collection_group(collection_id: str)

Creates and returns a new Query that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.

>>> query = client.collection_group('mygroup')

  • Parameters

    collection_id (str) – Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash.

  • Returns

    The created Query.

  • Return type

    CollectionGroup

collections(retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

List top-level collections of the client’s database.

  • 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

    iterator of subcollections of the current document.

  • Return type

    Sequence[CollectionReference]

document(*document_path: Tuple[str])

Get a reference to a document in a collection.

For a top-level document:

>>> client.document('collek/shun')
>>> # is the same as
>>> client.document('collek', 'shun')

For a document in a sub-collection:

>>> client.document('mydocs/doc/subcol/child')
>>> # is the same as
>>> client.document('mydocs', 'doc', 'subcol', 'child')

Documents in sub-collections can be nested deeper in a similar fashion.

  • Parameters

    document_path (Tuple[str, **...]) – Can either be

    • A single /-delimited path to a document

    • A tuple of document path segments

  • Returns

    A reference to a document in a collection.

  • Return type

    DocumentReference

get_all(references: list, field_paths: Optional[Iterable[str]] = None, transaction: Optional[google.cloud.firestore_v1.transaction.Transaction] = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE:

Retrieve a batch of documents.

NOTE: Documents returned by this method are not guaranteed to be returned in the same order that they are given in references.

NOTE: If multiple references refer to the same document, the server will only return one result.

See field_path() for more information on field paths.

If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

  • Parameters

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

    • field_paths (Optional[Iterable[str, **...]]) – An iterable of field paths (.-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned.

    • transaction (Optional[Transaction]) – An existing transaction that these references will be retrieved in.

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

transaction(**kwargs)

Get a transaction that uses this client.

See Transaction for more information on transactions and the constructor arguments.

  • Parameters

    kwargs (Dict[str, **Any]) – The keyword arguments (other than client) to pass along to the Transaction constructor.

  • Returns

    A transaction attached to this client.

  • Return type

    Transaction