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

• a Client owns a CollectionReference

• a Client owns a DocumentReference

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