Firebase.Firestore.FirebaseFirestore

Represents a Cloud Firestore database and is the entry point for all Cloud Firestore operations.

Summary

Properties
App
Returns the FirebaseApp instance to which this FirebaseFirestore belongs.
DefaultInstance
Gets the instance of FirebaseFirestore for the default FirebaseApp with the default database name.
LogLevel
static LogLevel
Sets the log verbosity of all Firestore instances.
Settings
The settings of this FirebaseFirestore object.

Public static functions
GetInstance(FirebaseApp app)
Gets an instance of FirebaseFirestore for a specific FirebaseApp with the default database name.
GetInstance(string database)
Gets an instance of FirebaseFirestore for the default FirebaseApp with a spesific database name.
GetInstance(FirebaseApp app, string database)
Gets an instance of FirebaseFirestore for a specific FirebaseApp with a spesific database name.

Public functions
ClearPersistenceAsync()
Task
Clears the persistent storage.
Collection(string path)
Creates a local CollectionReference for the given path, which must include an odd number of slash-separated identifiers.
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.
DisableNetworkAsync()
Task
Disables network access for this instance.
Document(string path)
Creates a local DocumentReference for the given path, which must include an even number of slash-separated identifiers.
EnableNetworkAsync()
Task
Re-enables network usage for this instance after a prior call to FirebaseFirestore.DisableNetworkAsync.
GetNamedQueryAsync(string queryName)
Task< Query >
Reads a FirestoreQuery from the local cache, identified by the given name.
ListenForSnapshotsInSync(Action callback)
Attaches a listener for a snapshots-in-sync event.
LoadBundleAsync(string bundleData)
Loads a Firestore bundle into the local cache.
LoadBundleAsync(string bundleData, System.EventHandler< LoadBundleTaskProgress > progressHandler)
Loads a Firestore bundle into the local cache, taking an System.EventHandler to monitor loading progress.
LoadBundleAsync(byte[] bundleData)
Loads a Firestore bundle into the local cache.
LoadBundleAsync(byte[] bundleData, System.EventHandler< LoadBundleTaskProgress > progressHandler)
Loads a Firestore bundle into the local cache, taking an System.EventHandler to monitor loading progress.
RunTransactionAsync(Func< Transaction, Task > callback)
Task
Runs a transaction asynchronously, with an asynchronous callback that doesn't return a value.
RunTransactionAsync(TransactionOptions options, Func< Transaction, Task > callback)
Task
Runs a transaction asynchronously, with an asynchronous callback that doesn't return a value.
RunTransactionAsync< T >(Func< Transaction, Task< T >> callback)
Task< T >
Runs a transaction asynchronously, with an asynchronous callback that returns a value.
RunTransactionAsync< T >(TransactionOptions options, Func< Transaction, Task< T >> callback)
Task< T >
Runs a transaction asynchronously, with an asynchronous callback that returns a value.
StartBatch()
Creates a write batch, which can be used to commit multiple mutations atomically.
TerminateAsync()
Task
Terminates this FirebaseFirestore instance.
WaitForPendingWritesAsync()
Task
Waits until all currently pending writes for the active user have been acknowledged by the backend.

Properties

App

FirebaseApp App

Returns the FirebaseApp instance to which this FirebaseFirestore belongs.

DefaultInstance

static FirebaseFirestore DefaultInstance

Gets the instance of FirebaseFirestore for the default FirebaseApp with the default database name.

A FirebaseFirestore instance.

LogLevel

static LogLevel LogLevel

Sets the log verbosity of all Firestore instances.

The default verbosity level is Info Set to Debug to turn on the diagnostic logging.

The desired verbosity.

Settings

FirebaseFirestoreSettings Settings

The settings of this FirebaseFirestore object.

To change the settings used by this FirebaseFirestore instance, simply change the values of the properties on this FirebaseFirestoreSettings object.

Invoking any non-static method on this FirebaseFirestore instance will "lock in" the settings. No changes are allowed to be made to the settings once they are locked in. Attempting to do so will result in an exception being thrown by the property setter.

Public static functions

GetInstance

FirebaseFirestore GetInstance(
  FirebaseApp app
)

Gets an instance of FirebaseFirestore for a specific FirebaseApp with the default database name.

Details
Parameters
app
The FirebaseApp for which to get a FirebaseFirestore instance.
Returns
A FirebaseFirestore instance.

GetInstance

FirebaseFirestore GetInstance(
  string database
)

Gets an instance of FirebaseFirestore for the default FirebaseApp with a spesific database name.

Details
Parameters
database
The customized name for the database. instance.
Returns
A FirebaseFirestore instance.

GetInstance

FirebaseFirestore GetInstance(
  FirebaseApp app,
  string database
)

Gets an instance of FirebaseFirestore for a specific FirebaseApp with a spesific database name.

Details
Parameters
app
The FirebaseApp for which to get a FirebaseFirestore
Parameters
database
The customized name for the database. instance.
Returns
A FirebaseFirestore instance.

Public functions

ClearPersistenceAsync

Task ClearPersistenceAsync()

Clears the persistent storage.

This includes pending writes and cached documents.

Must be called while the Firestore instance is not started (after the app is shut down or when the app is first initialized). On startup, this method must be called before other methods (other than getting or setting FirebaseFirestoreSettings). If the Firestore instance is still running, the task will complete with an error code of FailedPrecondition.

Note: ClearPersistenceAsync() is primarily intended to help write reliable tests that use Firestore. It uses the most efficient mechanism possible for dropping existing data but does not attempt to securely overwrite or otherwise make cached data unrecoverable. For applications that are sensitive to the disclosure of cache data in between user sessions we strongly recommend not to enable persistence in the first place.

Details
Returns
A Task which completes when the clear persistence operation has completed.

Collection

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.

Details
Parameters
path
The collection path, e.g. col1/doc1/col2.
Returns
A collection reference.

CollectionGroup

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.

Details
Parameters
collectionId
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
The created Query.

DisableNetworkAsync

Task DisableNetworkAsync()

Disables network access for this instance.

While the network is disabled, any snapshot listeners or GetSnapshotAsync calls will return results from cache, and any write operations will be queued until network usage is re-enabled via a call to FirebaseFirestore.EnableNetworkAsync.

Details
Returns
A task which completes once networking is disabled.

Document

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.

Details
Parameters
path
The document path, e.g. col1/doc1/col2/doc2.
Returns
A document reference.

EnableNetworkAsync

Task EnableNetworkAsync()

Re-enables network usage for this instance after a prior call to FirebaseFirestore.DisableNetworkAsync.

Details
Returns
A task which completes once networking is enabled.

GetNamedQueryAsync

Task< Query > GetNamedQueryAsync(
  string queryName
)

Reads a FirestoreQuery from the local cache, identified by the given name.

Named queries are packaged into bundles on the server side (along with the resulting documents) and loaded into local cache using FirebaseFirestore.LoadBundleAsync(string). Once in the local cache, you can use this method to extract a query by name.

Details
Parameters
queryName
The name of the query to read from saved bundles.
Returns
A task that is completed with the query associated with the given name. The result of the returned task is set to null if no queries can be found.

ListenForSnapshotsInSync

ListenerRegistration ListenForSnapshotsInSync(
  Action callback
)

Attaches a listener for a snapshots-in-sync event.

The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.

NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server.

Details
Parameters
callback
A callback to be called every time all snapshot listeners are in sync with each other. The callback will be invoked on the main thread.
Returns
A registration object that can be used to remove the listener.

LoadBundleAsync

Task< LoadBundleTaskProgress > LoadBundleAsync(
  string bundleData
)

Loads a Firestore bundle into the local cache.

Details
Parameters
bundleData
The bundle to be loaded.
Returns
A task that is completed when the loading is completed. The result of the task then contains the final progress of the loading operation.

LoadBundleAsync

Task< LoadBundleTaskProgress > LoadBundleAsync(
  string bundleData,
  System.EventHandler< LoadBundleTaskProgress > progressHandler
)

Loads a Firestore bundle into the local cache, taking an System.EventHandler to monitor loading progress.

Details
Parameters
bundleData
The bundle to be loaded.
progressHandler
A System.EventHandler that is notified with progress updates, and completion or error updates. The handler will be invoked on the main thread.
Returns
A task that is completed when the loading is completed. The result of the task then contains the final progress of the loading operation.

LoadBundleAsync

Task< LoadBundleTaskProgress > LoadBundleAsync(
  byte[] bundleData
)

Loads a Firestore bundle into the local cache.

Details
Parameters
bundleData
The bundle to be loaded, as a UTF-8 encoded byte array.
Returns
A task that is completed when the loading is completed. The result of the task then contains the final progress of the loading operation.

LoadBundleAsync

Task< LoadBundleTaskProgress > LoadBundleAsync(
  byte[] bundleData,
  System.EventHandler< LoadBundleTaskProgress > progressHandler
)

Loads a Firestore bundle into the local cache, taking an System.EventHandler to monitor loading progress.

Details
Parameters
bundleData
The bundle to be loaded, as a UTF8 encoded byte array.
progressHandler
An System.EventHandler that is notified with progress updates, and completion or error updates. The handler will be invoked on the main thread.
Returns
A task that is completed when the loading is completed. The result of the task then contains the final progress of the loading operation.

RunTransactionAsync

Task RunTransactionAsync(
  Func< Transaction, Task > callback
)

Runs a transaction asynchronously, with an asynchronous callback that doesn't return a value.

The specified callback is executed for a newly-created transaction.

RunTransactionAsync executes the given callback on the main thread and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the callback will be retried. If it fails to commit after 5 attempts, the transaction will fail.

The maximum number of writes allowed in a single transaction is 500, but note that each usage of FieldValue.ServerTimestamp, FieldValue.ArrayUnion, FieldValue.ArrayRemove, or FieldValue.Increment inside a transaction counts as an additional write.

Details
Parameters
callback
The callback to execute. Must not be null. The callback will be invoked on the main thread.
Returns
A task which completes when the transaction has committed.

RunTransactionAsync

Task RunTransactionAsync(
  TransactionOptions options,
  Func< Transaction, Task > callback
)

Runs a transaction asynchronously, with an asynchronous callback that doesn't return a value.

The specified callback is executed for a newly-created transaction.

RunTransactionAsync executes the given callback on the main thread and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the callback will be retried. If it fails to commit after the maximum number of attempts specified in the given TransactionOptions object, the transaction will fail.

The maximum number of writes allowed in a single transaction is 500, but note that each usage of FieldValue.ServerTimestamp, FieldValue.ArrayUnion, FieldValue.ArrayRemove, or FieldValue.Increment inside a transaction counts as an additional write.

Details
Parameters
options
The transaction options for controlling execution. Must not be null.
callback
The callback to execute. Must not be null. The callback will be invoked on the main thread.
Returns
A task which completes when the transaction has committed.

RunTransactionAsync< T >

Task< T > RunTransactionAsync< T >(
  Func< Transaction, Task< T >> callback
)

Runs a transaction asynchronously, with an asynchronous callback that returns a value.

The specified callback is executed for a newly-created transaction.

RunTransactionAsync executes the given callback on the main thread and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the callback will be retried. If it fails to commit after 5 attempts, the transaction will fail.

The maximum number of writes allowed in a single transaction is 500, but note that each usage of FieldValue.ServerTimestamp, FieldValue.ArrayUnion, FieldValue.ArrayRemove, or FieldValue.Increment inside a transaction counts as an additional write.

Details
Template Parameters
T
The result type of the callback.
Parameters
callback
The callback to execute. Must not be null. The callback will be invoked on the main thread.
Returns
A task which completes when the transaction has committed. The result of the task then contains the result of the callback.

RunTransactionAsync< T >

Task< T > RunTransactionAsync< T >(
  TransactionOptions options,
  Func< Transaction, Task< T >> callback
)

Runs a transaction asynchronously, with an asynchronous callback that returns a value.

The specified callback is executed for a newly-created transaction.

RunTransactionAsync executes the given callback on the main thread and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the callback will be retried. If it fails to commit after the maximum number of attempts specified in the given TransactionOptions object, the transaction will fail.

The maximum number of writes allowed in a single transaction is 500, but note that each usage of FieldValue.ServerTimestamp, FieldValue.ArrayUnion, FieldValue.ArrayRemove, or FieldValue.Increment inside a transaction counts as an additional write.

Details
Template Parameters
T
The result type of the callback.
Parameters
options
The transaction options for controlling execution. Must not be null.
callback
The callback to execute. Must not be null. The callback will be invoked on the main thread.
Returns
A task which completes when the transaction has committed. The result of the task then contains the result of the callback.

StartBatch

WriteBatch StartBatch()

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

Details
Returns
A write batch for this database.

TerminateAsync

Task TerminateAsync()

Terminates this FirebaseFirestore instance.

After calling Terminate(), only the ClearPersistenceAsync() method may be used. Calling any other method will result in an error.

To restart after termination, simply create a new instance of FirebaseFirestore with GetInstance() methods.

Terminate() does not cancel any pending writes, and any tasks that are awaiting a response from the server will not be resolved. The next time you start this instance, it will resume attempting to send these writes to the server.

Note: under normal circumstances, calling Terminate() is not required. This method is useful only when you want to force this instance to release all of its resources or in combination with ClearPersistenceAsync to ensure that all local state is destroyed between test runs.

Details
Returns
A Task which completes when the instance has been successfully terminated.

WaitForPendingWritesAsync

Task WaitForPendingWritesAsync()

Waits until all currently pending writes for the active user have been acknowledged by the backend.

The returned Task completes immediately if there are no outstanding writes. Otherwise, the Task waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the method is called. If you wish to wait for additional writes, you have to call WaitForPendingWritesAsync() again.

Any outstanding WaitForPendingWritesAsync() Tasks are cancelled during user changes.

Details
Returns
A Task which completes when all currently pending writes have been acknowledged by the backend.