Firestore API - Class FirestoreDb (3.12.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

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
TaskSystem.Collections.Generic.IList`1DocumentSnapshot

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
TaskSystem.Collections.Generic.IList`1DocumentSnapshot

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.