Firestore API - Class FirestoreDb (3.6.0)

public sealed class FirestoreDb

Reference documentation and code samples for the Firestore API class FirestoreDb.

A Firestore database. Create instances using the static Create(string, FirestoreClient) and CreateAsync(string, FirestoreClient) methods, or using a FirestoreDbBuilder.

Inheritance

object > FirestoreDb

Inherited Members

object.GetHashCode()

object.GetType()

object.ToString()

Namespace

Google.Cloud.Firestore

Assembly

Google.Cloud.Firestore.dll

Properties

Client

public FirestoreClient Client { get; }

The underlying client used to make service requests.

Property Value
Type	Description
`Google.Cloud.Firestore.V1.FirestoreClient`

DatabaseId

public string DatabaseId { get; }

The database ID associated with this database.The value will be "(default)" for the project-default database.

Property Value
Type	Description
`string`

ProjectId

public string ProjectId { get; }

The project ID associated with this database.

Property Value
Type	Description
`string`

Methods

Collection(string)

public CollectionReference Collection(string path)

Creates a local CollectionReference for the given path, which must include an odd number of slash-separated identifiers. This does not perform any remote operations.

Parameter
Name	Description
`path`	`string` The collection path, e.g. `col1/doc1/col2`.

Returns
Type	Description
`CollectionReference`	A collection reference.

CollectionGroup(string)

public Query CollectionGroup(string collectionId)

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.

Parameter
Name	Description
`collectionId`	`string` Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Must not contain a slash.

Returns
Type	Description
`Query`	The created Query.

Create(string, FirestoreClient)

public static FirestoreDb Create(string projectId = null, FirestoreClient client = null)

Creates an instance for the specified project, using the specified Google.Cloud.Firestore.V1.FirestoreClient for RPC operations.

Parameters
Name	Description
`projectId`	`string` The ID of the Google Cloud project that contains the database. May be null, in which case the project will be automatically detected if possible.
`client`	`Google.Cloud.Firestore.V1.FirestoreClient` The client to use for RPC operations. May be null, in which case a client will be created with default credentials.

Returns
Type	Description
`FirestoreDb`	A new instance.

CreateAsync(string, FirestoreClient)

public static Task<FirestoreDb> CreateAsync(string projectId = null, FirestoreClient client = null)

Asynchronously creates an instance for the specified project, using the specified Google.Cloud.Firestore.V1.FirestoreClient for RPC operations.

Parameters
Name	Description
`projectId`	`string` The ID of the Google Cloud project that contains the database. May be null, in which case the project will be automatically detected if possible.
`client`	`Google.Cloud.Firestore.V1.FirestoreClient` The client to use for RPC operations. May be null, in which case a client will be created with default credentials.

Returns
Type	Description
`TaskFirestoreDb`	A task representing the asynchronous operation. When complete, the result of the task is the new instance.

Document(string)

public DocumentReference Document(string path)

Creates a local DocumentReference for the given path, which must include an even number of slash-separated identifiers. This does not perform any remote operations.

Parameter
Name	Description
`path`	`string` The document path, e.g. `col1/doc1/col2/doc2`.

Returns
Type	Description
`DocumentReference`	A document reference.

GetAllSnapshotsAsync(IEnumerable<DocumentReference>, FieldMask, CancellationToken)

public Task<IList<DocumentSnapshot>> GetAllSnapshotsAsync(IEnumerable<DocumentReference> documents, FieldMask fieldMask, CancellationToken cancellationToken = default)

Fetches document snapshots from the server, potentially limiting the fields returned.

Parameters
Name	Description
`documents`	`IEnumerableDocumentReference` The document references to fetch. Must not be null, or contain null references.
`fieldMask`	`FieldMask` The field mask to use to restrict which fields are retrieved. May be null, in which case no field mask is applied, and the complete documents are retrieved.
`cancellationToken`	`CancellationToken` A cancellation token for the operation.

Returns
Type	Description
`TaskIListDocumentSnapshot`	The document snapshots, in the same order as `documents`.

Remarks

Any documents which are missing are represented in the returned list by a DocumentSnapshot with Exists value of false.

GetAllSnapshotsAsync(IEnumerable<DocumentReference>, CancellationToken)

public Task<IList<DocumentSnapshot>> GetAllSnapshotsAsync(IEnumerable<DocumentReference> documents, CancellationToken cancellationToken = default)

Fetches document snapshots from the server.

Parameters
Name	Description
`documents`	`IEnumerableDocumentReference` The document references to fetch. Must not be null, or contain null references.
`cancellationToken`	`CancellationToken` A cancellation token for the operation.

Returns
Type	Description
`TaskIListDocumentSnapshot`	The document snapshots, in the same order as `documents`.

Remarks

Any documents which are missing are represented in the returned list by a DocumentSnapshot with Exists value of false.

ListRootCollectionsAsync()

public IAsyncEnumerable<CollectionReference> ListRootCollectionsAsync()

Asynchronously retrieves the root collection IDs from the server.

Returns
Type	Description
`IAsyncEnumerableCollectionReference`	All the root collection references, in a lazily-iterated sequence.

RunTransactionAsync(Func<Transaction, Task>, TransactionOptions, CancellationToken)

public Task RunTransactionAsync(Func<Transaction, Task> callback, TransactionOptions options = null, CancellationToken cancellationToken = default)

Runs a transaction asynchronously, with an asynchronous callback that doesn't return a value. The specified callback is executed for a newly-created transaction. If committing the transaction fails, the whole operation is retried based on MaxAttempts.

Parameters
Name	Description
`callback`	`FuncTransactionTask` The callback to execute. Must not be null.
`options`	`TransactionOptions` The options for the transaction. May be null, in which case default options will be used.
`cancellationToken`	`CancellationToken` A cancellation token for the operation. This is exposed to the callback through CancellationToken and applied to all RPCs to begin, rollback or commit the transaction.

Returns
Type	Description
`Task`	A task which completes when the transaction has committed.

RunTransactionAsync<T>(Func<Transaction, Task<T>>, TransactionOptions, CancellationToken)

public Task<T> RunTransactionAsync<T>(Func<Transaction, Task<T>> callback, TransactionOptions options = null, CancellationToken cancellationToken = default)

Runs a transaction asynchronously, with an asynchronous callback that returns a value. The specified callback is executed for a newly-created transaction. If committing the transaction fails, the whole operation is retried based on MaxAttempts.

Parameters
Name	Description
`callback`	`FuncTransactionTask` The callback to execute. Must not be null.
`options`	`TransactionOptions` The options for the transaction. May be null, in which case default options will be used.
`cancellationToken`	`CancellationToken` A cancellation token for the operation. This is exposed to the callback through CancellationToken and applied to all RPCs to begin, rollback or commit the transaction.

Returns
Type	Description
`Task`	A task which completes when the transaction has committed. The result of the task then contains the result of the callback.

Type Parameter
Name	Description
`T`	The result type of the callback.

StartBatch()

public WriteBatch StartBatch()

Creates a write batch, which can be used to commit multiple mutations atomically.

Returns
Type	Description
`WriteBatch`	A write batch for this database.

WithWarningLogger(Action<string>)

public FirestoreDb WithWarningLogger(Action<string> warningLogger)

Returns a new FirestoreDb with the same project, database and client as this one, but the given writer for warning logs.

Parameter
Name	Description
`warningLogger`	`Actionstring` The logger for warnings. May be null.

Returns
Type	Description
`FirestoreDb`	A new FirestoreDb based on this one, with the given warning logger.