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

GoogleCloudFirestore

Assembly

Google.Cloud.Firestore.dll

Properties

Client

public FirestoreClient Client { get; }

The underlying client used to make service requests.

Property Value
TypeDescription
FirestoreClient

ProjectId

public string ProjectId { get; }

The project ID associated with this database.

Property Value
TypeDescription
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
NameDescription
pathstring

The collection path, e.g. col1/doc1/col2.

Returns
TypeDescription
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
NameDescription
collectionIdstring

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
TypeDescription
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
NameDescription
projectIdstring

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.

clientFirestoreClient

The client to use for RPC operations. May be null, in which case a client will be created with default credentials.

Returns
TypeDescription
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
NameDescription
projectIdstring

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.

clientFirestoreClient

The client to use for RPC operations. May be null, in which case a client will be created with default credentials.

Returns
TypeDescription
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
NameDescription
pathstring

The document path, e.g. col1/doc1/col2/doc2.

Returns
TypeDescription
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
NameDescription
documentsIEnumerableDocumentReference

The document references to fetch. Must not be null, or contain null references.

fieldMaskFieldMask

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.

cancellationTokenCancellationToken

A cancellation token for the operation.

Returns
TypeDescription
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
NameDescription
documentsIEnumerableDocumentReference

The document references to fetch. Must not be null, or contain null references.

cancellationTokenCancellationToken

A cancellation token for the operation.

Returns
TypeDescription
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
TypeDescription
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
NameDescription
callbackFuncTransactionTask

The callback to execute. Must not be null.

optionsTransactionOptions

The options for the transaction. May be null, in which case default options will be used.

cancellationTokenCancellationToken

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
TypeDescription
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
NameDescription
callbackFuncTransactionTask

The callback to execute. Must not be null.

optionsTransactionOptions

The options for the transaction. May be null, in which case default options will be used.

cancellationTokenCancellationToken

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
TypeDescription
Task

A task which completes when the transaction has committed. The result of the task then contains the result of the callback.

Type Parameter
NameDescription
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
TypeDescription
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
NameDescription
warningLoggerActionstring

The logger for warnings. May be null.

Returns
TypeDescription
FirestoreDb

A new FirestoreDb based on this one, with the given warning logger.