The Cloud Firestore service interface.

Do not call this constructor directly. Instead, use firebase.firestore().

Index

Constructors

Properties

Methods

Constructors

Private constructor

Properties

app

app: App

The app associated with this Firestore service instance.

Methods

batch

  • batch ( ) : WriteBatch

  • Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500, but note that each usage of FieldValue.serverTimestamp(), FieldValue.arrayUnion(), FieldValue.arrayRemove(), or FieldValue.increment() inside a WriteBatch counts as an additional write.

    Returns WriteBatch

    A WriteBatch that can be used to atomically execute multiple writes.

clearPersistence

  • clearPersistence ( ) : Promise < void >

  • 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 shutdown or when the app is first initialized). On startup, this method must be called before other methods (other than settings()). If the firestore instance is still running, the promise will be rejected with the error code of failed-precondition.

    Note: clearPersistence() is primarily intended to help write reliable tests that use Cloud Firestore. It uses an efficient mechanism 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 cached data in between user sessions, we strongly recommend not enabling persistence at all.

    Returns Promise<void>

    A promise that is resolved when the persistent storage is cleared. Otherwise, the promise is rejected with an error.

collection

collectionGroup

  • collectionGroup ( collectionId :  string ) : Query < DocumentData >

  • Creates and returns a new Query that includes all documents in the database that are contained in a collection or subcollection with the given collectionId.

    Parameters

    • 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. Cannot contain a slash.

    Returns Query<DocumentData>

    The created Query.

disableNetwork

  • disableNetwork ( ) : Promise < void >

  • Disables network usage for this instance. It can be re-enabled via enableNetwork(). While the network is disabled, any snapshot listeners or get() calls will return results from cache, and any write operations will be queued until the network is restored.

    Returns Promise<void>

    A promise that is resolved once the network has been disabled.

doc

enableNetwork

  • enableNetwork ( ) : Promise < void >

  • Re-enables use of the network for this Firestore instance after a prior call to disableNetwork().

    Returns Promise<void>

    A promise that is resolved once the network has been enabled.

enablePersistence

  • enablePersistence ( settings ? :  PersistenceSettings ) : Promise < void >

  • Attempts to enable persistent storage, if possible.

    Must be called before any other methods (other than settings() and clearPersistence()).

    If this fails, enablePersistence() will reject the promise it returns. Note that even after this failure, the firestore instance will remain usable, however offline persistence will be disabled.

    There are several reasons why this can fail, which can be identified by the code on the error.

    • failed-precondition: The app is already open in another browser tab.
    • unimplemented: The browser is incompatible with the offline persistence implementation.

    Parameters

    Returns Promise<void>

    A promise that represents successfully enabling persistent storage.

loadBundle

  • loadBundle ( bundleData :  ArrayBuffer | ReadableStream < Uint8Array > | string ) : LoadBundleTask

  • Loads a Firestore bundle into the local cache.

    Parameters

    • bundleData: ArrayBuffer | ReadableStream<Uint8Array> | string

      An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string.

    Returns LoadBundleTask

    A LoadBundleTask object, which notifies callers with progress updates, and completion or error events. It can be used as a Promise<LoadBundleTaskProgress>.

namedQuery

  • namedQuery ( name :  string ) : Promise < Query < DocumentData > | null >

  • Reads a Firestore Query from local cache, identified by the given name.

    The named queries are packaged into bundles on the server side (along with resulting documents), and loaded to local cache using loadBundle. Once in local cache, use this method to extract a Query by name.

    Parameters

    • name: string

    Returns Promise<Query<DocumentData> | null>

onSnapshotsInSync

  • onSnapshotsInSync ( observer :  { complete ?: ( ) => void ; error ?: ( error :  FirestoreError ) => void ; next ?: ( value :  void ) => void } ) : ( ) => void

  • 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.

    Parameters

    • observer: { complete?: () => void; error?: (error: FirestoreError) => void; next?: (value: void) => void }

      A single object containing next and error callbacks.

      • Optional complete?: () => void
          • (): void

          • Returns void

      • Optional error?: (error: FirestoreError) => void
      • Optional next?: (value: void) => void
          • (value: void): void

          • Parameters

            • value: void

            Returns void

    Returns () => void

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

  • onSnapshotsInSync ( onSync :  ( ) => void ) : ( ) => void

  • 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.

    Parameters

    • onSync: () => void

      A callback to be called every time all snapshot listeners are in sync with each other.

        • (): void

        • Returns void

    Returns () => void

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

runTransaction

  • runTransaction < T > ( updateFunction :  ( transaction :  Transaction ) => Promise < T > ) : Promise < T >

  • Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.

    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.

    Type parameters

    • T

    Parameters

    • updateFunction: (transaction: Transaction) => Promise<T>

      The function to execute within the transaction context.

    Returns Promise<T>

    If the transaction completed successfully or was explicitly aborted (the updateFunction returned a failed promise), the promise returned by the updateFunction is returned here. Else, if the transaction failed, a rejected promise with the corresponding failure error will be returned.

settings

  • settings ( settings :  Settings ) : void

  • Specifies custom settings to be used to configure the Firestore instance. Must be set before invoking any other methods.

    Parameters

    • settings: Settings

      The settings to use.

    Returns void

terminate

  • terminate ( ) : Promise < void >

  • Terminates this Firestore instance.

    After calling terminate() only the clearPersistence() method may be used. Any other method will throw a FirestoreError.

    To restart after termination, create a new instance of FirebaseFirestore with firebase.firestore().

    Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending 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 clearPersistence() to ensure that all local state is destroyed between test runs.

    Returns Promise<void>

    A promise that is resolved when the instance has been successfully terminated.

useEmulator

  • useEmulator ( host :  string ,  port :  number ,  options ? :  { mockUserToken ?: EmulatorMockTokenOptions | string } ) : void

  • Modify this instance to communicate with the Cloud Firestore emulator.

    Note: this must be called before this instance has been used to do any operations.

    Parameters

    • host: string

      the emulator host (ex: localhost).

    • port: number

      the emulator port (ex: 9000).

    • Optional options: { mockUserToken?: EmulatorMockTokenOptions | string }
      • Optional mockUserToken?: EmulatorMockTokenOptions | string

        the mock auth token to use for unit testing Security Rules.

    Returns void

waitForPendingWrites

  • waitForPendingWrites ( ) : Promise < void >

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

    The returned Promise resolves immediately if there are no outstanding writes. Otherwise, the Promise 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 want to wait for additional writes, call waitForPendingWrites() again.

    Any outstanding waitForPendingWrites() Promises are rejected during user changes.

    Returns Promise<void>

    A Promise which resolves when all currently pending writes have been acknowledged by the backend.