The Firestore client represents a Firestore Database and is the entry point for all Firestore operations.
[Firestore Documentation]https://firebase.google.com/docs/firestore/
Package
@google-cloud/firestore!Constructors
(constructor)(settings)
constructor(settings?: firestore.Settings);
Constructs a new instance of the Firestore
class
Name | Description |
settings |
firestore.Settings
[Configuration object](#/docs). |
Methods
batch()
batch(): WriteBatch;
Creates a [WriteBatch]WriteBatch, used for performing multiple writes as a single atomic operation.
Type | Description |
WriteBatch | {WriteBatch} A WriteBatch that operates on this Firestore client. |
bulkWriter(options)
bulkWriter(options?: firestore.BulkWriterOptions): BulkWriter;
Creates a [BulkWriter]BulkWriter, used for performing multiple writes in parallel. Gradually ramps up writes as specified by the 500/50/5 rule.
If you pass [BulkWriterOptions], you can configure the throttling rates for the created BulkWriter.
[500/50/5 Documentation]https://firebase.google.com/docs/firestore/best-practices#ramping_up_traffic
Name | Description |
options |
firestore.BulkWriterOptions
BulkWriter options. |
Type | Description |
BulkWriter | {BulkWriter} A BulkWriter that operates on this Firestore client. |
bundle(name)
bundle(name?: string): BundleBuilder;
Creates a new BundleBuilder
instance to package selected Firestore data into a bundle.
Name | Description |
name |
string
|
Type | Description |
BundleBuilder |
collection(collectionPath)
collection(collectionPath: string): CollectionReference;
Gets a [CollectionReference]CollectionReference instance that refers to the collection at the specified path.
Name | Description |
collectionPath |
string
A slash-separated path to a collection. |
Type | Description |
CollectionReference | {CollectionReference} The [CollectionReference]CollectionReference instance. |
collectionGroup(collectionId)
collectionGroup(collectionId: string): CollectionGroup;
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.
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. Cannot contain a slash. |
Type | Description |
CollectionGroup | {CollectionGroup} The created CollectionGroup. |
doc(documentPath)
doc(documentPath: string): DocumentReference;
Gets a [DocumentReference]DocumentReference instance that refers to the document at the specified path.
Name | Description |
documentPath |
string
A slash-separated path to a document. |
Type | Description |
DocumentReference | {DocumentReference} The [DocumentReference]DocumentReference instance. |
getAll(documentRefsOrReadOptions)
getAll<T>(...documentRefsOrReadOptions: Array<firestore.DocumentReference<T> | firestore.ReadOptions>): Promise<Array<DocumentSnapshot<T>>>;
Retrieves multiple documents from Firestore.
The first argument is required and must be of type DocumentReference
followed by any additional DocumentReference
documents. If used, the optional ReadOptions
must be the last argument.
Name | Description |
documentRefsOrReadOptions |
Array<FirebaseFirestore.DocumentReference<T> | FirebaseFirestore.ReadOptions>
The |
Type | Description |
Promise<Array<DocumentSnapshot<T>>> | {Promise<Array.
|
Name | Description |
T |
listCollections()
listCollections(): Promise<CollectionReference[]>;
Fetches the root collections that are associated with this Firestore database.
Type | Description |
Promise<CollectionReference[]> | {Promise.<Array.
|
recursiveDelete(ref, bulkWriter)
recursiveDelete(ref: firestore.CollectionReference<unknown> | firestore.DocumentReference<unknown>, bulkWriter?: BulkWriter): Promise<void>;
Recursively deletes all documents and subcollections at and under the specified level.
If any delete fails, the promise is rejected with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.
recursiveDelete()
uses a BulkWriter instance with default settings to perform the deletes. To customize throttling rates or add success/error callbacks, pass in a custom BulkWriter instance.
Name | Description |
ref |
FirebaseFirestore.CollectionReference<unknown> | FirebaseFirestore.DocumentReference<unknown>
The reference of a document or collection to delete. |
bulkWriter |
BulkWriter
A custom BulkWriter instance used to perform the deletes. A promise that resolves when all deletes have been performed. The promise is rejected if any of the deletes fail. |
Type | Description |
Promise<void> |
runTransaction(updateFunction, transactionOptions)
runTransaction<T>(updateFunction: (transaction: Transaction) => Promise<T>, transactionOptions?: firestore.ReadWriteTransactionOptions | firestore.ReadOnlyTransactionOptions): Promise<T>;
Executes the given updateFunction and commits the changes applied within the transaction.
You can use the transaction object passed to 'updateFunction' to read and modify Firestore documents under lock. You have to perform all reads before before you perform any write.
Transactions can be performed as read-only or read-write transactions. By default, transactions are executed in read-write mode.
A read-write transaction obtains a pessimistic lock on all documents that are read during the transaction. These locks block other transactions, batched writes, and other non-transactional writes from changing that document. Any writes in a read-write transactions are committed once 'updateFunction' resolves, which also releases all locks.
If a read-write transaction fails with contention, the transaction is retried up to five times. The updateFunction
is invoked once for each attempt.
Read-only transactions do not lock documents. They can be used to read documents at a consistent snapshot in time, which may be up to 60 seconds in the past. Read-only transactions are not retried.
Transactions time out after 60 seconds if no documents are read. Transactions that are not committed within than 270 seconds are also aborted. Any remaining locks are released when a transaction times out.
T
Name | Description |
updateFunction |
(transaction: Transaction) => Promise<T>
The user function to execute within the transaction context. |
transactionOptions |
FirebaseFirestore.ReadWriteTransactionOptions | FirebaseFirestore.ReadOnlyTransactionOptions
Transaction options. |
Type | Description |
Promise<T> | {Promise
|
Name | Description |
T |
settings(settings)
settings(settings: firestore.Settings): void;
Specifies custom settings to be used to configure the Firestore
instance. Can only be invoked once and before any other Firestore method.
If settings are provided via both settings()
and the Firestore
constructor, both settings objects are merged and any settings provided via settings()
take precedence.
Name | Description |
settings |
firestore.Settings
The settings to use for all Firestore operations. |
Type | Description |
void |
snapshot_(documentName, readTime, encoding)
snapshot_(documentName: string, readTime: string, encoding: 'json'): DocumentSnapshot;
Name | Description |
documentName |
string
|
readTime |
string
|
encoding |
'json'
|
Type | Description |
DocumentSnapshot |
snapshot_(document, readTime, encoding)
snapshot_(document: api.IDocument, readTime: google.protobuf.ITimestamp, encoding?: 'protobufJS'): QueryDocumentSnapshot;
Name | Description |
document |
api.IDocument
|
readTime |
google.protobuf.ITimestamp
|
encoding |
'protobufJS'
|
Type | Description |
QueryDocumentSnapshot |
snapshot_(document, readTime, encoding)
snapshot_(document: {
[k: string]: unknown;
}, readTime: string, encoding: 'json'): QueryDocumentSnapshot;
Name | Description |
document |
{
[k: string]: unknown;
}
|
readTime |
string
|
encoding |
'json'
|
Type | Description |
QueryDocumentSnapshot |
terminate()
terminate(): Promise<void>;
Terminates the Firestore client and closes all open streams.
A Promise that resolves when the client is terminated.
Type | Description |
Promise<void> |
toJSON()
toJSON(): object;
Returns the Project ID to serve as the JSON representation of this Firestore instance.
An object that contains the project ID (or undefined
if not yet available).
Type | Description |
object |