Firestore API - Class FirestoreDb (3.1.0)

Version 3.1.0

• 3.9.0 (latest)
• 3.8.0
• 3.7.0
• 3.6.0
• 3.5.1
• 3.4.0
• 3.3.0
• 3.2.0
• 3.1.0
• 3.0.0
• 2.5.0
• 2.4.0
• 2.3.1

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.MemberwiseClone()

object.ToString()

Namespace

GoogleCloudFirestore

Assembly

Google.Cloud.Firestore.dll

Properties

Client

public FirestoreClient Client { get; }

The underlying client used to make service requests.

Property Value
Type	Description
FirestoreClient

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 FirestoreClient for RPC operations.

Parameters
Name	Description
projectId	string The ID of the Google Cloud Platform project that contains the database. May be null, in which case the project will be automatically detected if possible.
client	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 FirestoreClient for RPC operations.

Parameters
Name	Description
projectId	string The ID of the Google Cloud Platform project that contains the database. May be null, in which case the project will be automatically detected if possible.
client	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.