Client(project=None, credentials=None, database='(default)', client_info=<google.api_core.gapic_v1.client_info.ClientInfo object>, client_options=None)Client for interacting with Google Cloud Firestore API.
Parameters | |
|---|---|
| Name | Description |
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[
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, |
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 |
client_options |
Union[dict, google.api_core.client_options.ClientOptions]
Client options used to set user options on the client. API Endpoint should be set through client_options. |
Methods
batch
batch()Get a batch instance from this client.
| Returns | |
|---|---|
| Type | Description |
WriteBatch | A "write" batch to be used for accumulating document changes and sending the changes all at once. |
collection
collection(*collection_path: 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.
| Returns | |
|---|---|
| Type | Description |
CollectionReference | A reference to a collection in the Firestore database. |
collection_group
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')
| Parameter | |
|---|---|
| Name | Description |
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 | |
|---|---|
| Type | Description |
CollectionGroup | The created Query. |
collections
collections(retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: Optional[float] = None)List top-level collections of the client's 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
The timeout for this request. Defaults to a system-specified value. |
| Returns | |
|---|---|
| Type | Description |
Sequence[CollectionReference] | iterator of subcollections of the current document. |
document
document(*document_path: 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.
| Returns | |
|---|---|
| Type | Description |
DocumentReference | A reference to a document in a collection. |
get_all
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: <object object>>, timeout: Optional[float] = None)Retrieve a batch of documents.
If multiple references refer to the same document, the server
will only return one result.
See xref_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 | |
|---|---|
| Name | Description |
references |
List[.DocumentReference, ...]
Iterable of document references to be retrieved. |
field_paths |
Optional[Iterable[str, ...]]
An iterable of field paths ( |
transaction |
Optional[Transaction]
An existing transaction that these |
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:
The timeout for this request. Defaults to a system-specified value. |
recursive_delete
recursive_delete(
reference: Union[
google.cloud.firestore_v1.collection.CollectionReference,
google.cloud.firestore_v1.document.DocumentReference,
],
*,
bulk_writer: Optional[BulkWriter] = None,
chunk_size: Optional[int] = 5000
)Deletes documents and their subcollections, regardless of collection name.
Passing a CollectionReference leads to each document in the collection getting deleted, as well as all of their descendents.
Passing a DocumentReference deletes that one document and all of its descendents.
| Parameter | |
|---|---|
| Name | Description |
bulk_writer |
Optional[:class:
The BulkWriter used to delete all matching documents. Supply this if you want to override the default throttling behavior. |
transaction
transaction(**kwargs)Get a transaction that uses this client.
See xref_Transaction for more information on transactions and the constructor arguments.
| Parameter | |
|---|---|
| Name | Description |
kwargs |
Dict[str, Any]
The keyword arguments (other than |
| Returns | |
|---|---|
| Type | Description |
Transaction | A transaction attached to this client. |