Home > @firebase/firestore > /

@firebase/firestore

Classes

Class	Description
Bytes	An immutable object representing an array of bytes.
CollectionReference	A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using query()).
DocumentReference	A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist.
DocumentSnapshot	A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence.
FieldPath	A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document.
FieldValue	Sentinel values that can be used when writing document fields with set() or update().
FirebaseFirestore	The Cloud Firestore service interface.Do not call this constructor directly. Instead, use getFirestore().
FirestoreError	An error returned by a Firestore operation.
GeoPoint	An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of [-90, 90]. Longitude values are in the range of [-180, 180].
LoadBundleTask	Represents the task of loading a Firestore bundle. It provides progress of bundle loading, as well as task completion and error events.The API is compatible with Promise<LoadBundleTaskProgress>.
Query	A Query refers to a Query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering.
QueryConstraint	A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking where(), orderBy(), startAt(), startAfter(), , endAt(), limit() or limitToLast() and can then be passed to query() to create a new query instance that also contains this QueryConstraint.
QueryDocumentSnapshot	A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'.
QuerySnapshot	A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties.
SnapshotMetadata	Metadata about a snapshot, describing the state of the snapshot.
Timestamp	A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the Timestamp definition.
Transaction	A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See runTransaction().
WriteBatch	A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling writeBatch(). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until WriteBatch.commit() is called.

Functions

Function	Description
addDoc(reference, data)	Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.
arrayRemove(elements)	Returns a special value that can be used with setDoc() or that tells the server to remove the given elements from any array value that already exists on the server. All instances of each element specified will be removed from the array. If the field being modified is not already an array it will be overwritten with an empty array.
arrayUnion(elements)	Returns a special value that can be used with setDoc() or updateDoc() that tells the server to union the given elements with any array value that already exists on the server. Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array it will be overwritten with an array containing exactly the specified elements.
clearIndexedDbPersistence(firestore)	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 terminated or when the app is first initialized). On startup, this function must be called before other functions (other than initializeFirestore() or getFirestore())). If the Firestore instance is still running, the promise will be rejected with the error code of failed-precondition.Note: clearIndexedDbPersistence() 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.
collection(firestore, path, pathSegments)	Gets a CollectionReference instance that refers to the collection at the specified absolute path.
collection(reference, path, pathSegments)	Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path.
collection(reference, path, pathSegments)	Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path.
collectionGroup(firestore, collectionId)	Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId.
deleteDoc(reference)	Deletes the document referred to by the specified DocumentReference.
deleteField()	Returns a sentinel for use with updateDoc() or setDoc() with {merge: true} to mark a field for deletion.
disableNetwork(firestore)	Disables network usage for this instance. It can be re-enabled via enableNetwork(). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored.
doc(firestore, path, pathSegments)	Gets a DocumentReference instance that refers to the document at the specified abosulute path.
doc(reference, path, pathSegments)	Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference.
doc(reference, path, pathSegments)	Gets a DocumentReference instance that refers to a document within reference at the specified relative path.
documentId()	Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID.
enableIndexedDbPersistence(firestore, persistenceSettings)	Attempts to enable persistent storage, if possible.Must be called before any other functions (other than initializeFirestore(), getFirestore() or clearIndexedDbPersistence().If this fails, enableIndexedDbPersistence() 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.
enableMultiTabIndexedDbPersistence(firestore)	Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() 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 and multi-tab is not enabled. * unimplemented: The browser is incompatible with the offline persistence implementation.
enableNetwork(firestore)	Re-enables use of the network for this Firestore instance after a prior call to disableNetwork().
endAt(snapshot)	Creates a QueryConstraint that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query.
endAt(fieldValues)	Creates a QueryConstraint that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
endBefore(snapshot)	Creates a QueryConstraint that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query.
endBefore(fieldValues)	Creates a QueryConstraint that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
getDoc(reference)	Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke getDocFromCache() or getDocFromServer().
getDocFromCache(reference)	Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached.
getDocFromServer(reference)	Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available.
getDocs(query)	Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke getDocsFromCache() or getDocsFromServer().
getDocsFromCache(query)	Executes the query and returns the results as a QuerySnapshot from cache. Returns an error if the document is not currently cached.
getDocsFromServer(query)	Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available.
getFirestore(app)	Returns the existing instance of Firestore that is associated with the provided FirebaseApp. If no instance exists, initializes a new instance with default settings.
increment(n)	Returns a special value that can be used with setDoc() or updateDoc() that tells the server to increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value.
initializeFirestore(app, settings)	Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other function, including getFirestore(). If the custom settings are empty, this function is equivalent to calling getFirestore().
limit(limit)	Creates a QueryConstraint that only returns the first matching documents.
limitToLast(limit)	Creates a QueryConstraint that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution.
loadBundle(firestore, bundleData)	Loads a Firestore bundle into the local cache.
namedQuery(firestore, name)	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.
onSnapshot(reference, observer)	Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(reference, options, observer)	Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(reference, onNext, onError, onCompletion)	Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(reference, options, onNext, onError, onCompletion)	Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(query, observer)	Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(query, options, observer)	Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(query, onNext, onError, onCompletion)	Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshot(query, options, onNext, onError, onCompletion)	Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.
onSnapshotsInSync(firestore, observer)	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.
onSnapshotsInSync(firestore, onSync)	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.
orderBy(fieldPath, directionStr)	Creates a QueryConstraint that sorts the query result by the specified field, optionally in descending order instead of ascending.
query(query, queryConstraints)	Creates a new immutable instance of Query that is extended to also include additional query constraints.
queryEqual(left, right)	Returns true if the provided queries point to the same collection and apply the same constraints.
refEqual(left, right)	Returns true if the provided references are equal.
runTransaction(firestore, updateFunction)	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.
serverTimestamp()	Returns a sentinel used with setDoc() or updateDoc() to include a server-generated timestamp in the written data.
setDoc(reference, data)	Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created.
setDoc(reference, data, options)	Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.
setLogLevel(logLevel)	Sets the verbosity of Cloud Firestore logs (debug, error, or silent).
snapshotEqual(left, right)	Returns true if the provided snapshots are equal.
startAfter(snapshot)	Creates a QueryConstraint that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query.
startAfter(fieldValues)	Creates a QueryConstraint that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
startAt(snapshot)	Creates a QueryConstraint that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.
startAt(fieldValues)	Creates a QueryConstraint that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.
terminate(firestore)	Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with getFirestore().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 function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs.
updateDoc(reference, data)	Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.
updateDoc(reference, field, value, moreFieldsAndValues)	Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.
useFirestoreEmulator(firestore, host, port)	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.
waitForPendingWrites(firestore)	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 function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() Promises are rejected during user changes.
where(fieldPath, opStr, value)	Creates a QueryConstraint that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided.
writeBatch(firestore)	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.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data.

Interfaces

Interface	Description
DocumentChange	A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred.
DocumentData	Document data (for use with setDoc()) consists of fields mapped to values.
FirestoreDataConverter	Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore.
LoadBundleTaskProgress	Represents a progress update or a final state from loading bundles.
PersistenceSettings	Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence.
Settings	Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods.
SnapshotListenOptions	An options object that can be passed to onSnapshot() and QuerySnapshot.docChanges() to control which types of changes to include in the result set.
SnapshotOptions	Options that configure how data is retrieved from a DocumentSnapshot (for example the desired behavior for server timestamps that have not yet been set to their final value).
Unsubscribe	A function returned by onSnapshot() that removes the listener when invoked.
UpdateData	Update data (for use with updateDoc()) consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document.

Variables

Variable	Description
CACHE_SIZE_UNLIMITED	Constant used to indicate the LRU garbage collection should be disabled. Set this value as the cacheSizeBytes on the settings passed to the Firestore instance.

Type Aliases

Type Alias	Description
DocumentChangeType	The type of a DocumentChange may be 'added', 'removed', or 'modified'.
FirestoreErrorCode	The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodesPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation.
OrderByDirection	The direction of a orderBy() clause is specified as 'desc' or 'asc' (descending or ascending).
QueryConstraintType	Describes the different query constraints available in this SDK.
SetOptions	An options object that configures the behavior of setDoc(), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true.
TaskState	Represents the state of bundle loading tasks.Both 'Error' and 'Success' are sinking state: task will abort or complete and there will be no more updates after they are reported.
WhereFilterOp	Filter conditions in a where() clause are specified using the strings '<', '<=', '==', '!=', '>=', '>', 'array-contains', 'in', 'array-contains-any', and 'not-in'.