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). |
Properties
_serializer
_serializer: Serializer | null;The serializer to use for the Protobuf transformation.
| Type | Description |
| Serializer | null |
_settings
_settings: firestore.Settings;The configuration options for the GAPIC client.
| Type | Description |
| firestore.Settings |
formattedName
get formattedName(): string;Returns the root path of the database. Validates that initializeIfNeeded() was called before.
| Type | Description |
| string |
projectId
get projectId(): string;Returns the Project ID for this Firestore instance. Validates that initializeIfNeeded() was called before.
| Type | Description |
| string |
Methods
_decrementBulkWritersCount()
_decrementBulkWritersCount(): void;Decrements the number of open BulkWriter instances. This is used to verify that all pending operations are complete when terminate() is called.
| Type | Description |
| void |
_getAllDescendants(ref)
_getAllDescendants(ref: CollectionReference | DocumentReference): NodeJS.ReadableStream;Retrieves all descendant documents nested under the provided reference.
{Stream
| Name | Description |
| ref |
CollectionReference | DocumentReference
|
| Type | Description |
| NodeJS.ReadableStream |
_incrementBulkWritersCount()
_incrementBulkWritersCount(): void;Increments the number of open BulkWriter instances. This is used to verify that all pending operations are complete when terminate() is called.
| Type | Description |
| void |
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_(docRefs, fieldMask, requestTag, transactionId)
getAll_<T>(docRefs: Array<firestore.DocumentReference<T>>, fieldMask: firestore.FieldPath[] | null, requestTag: string, transactionId?: Uint8Array): Promise<Array<DocumentSnapshot<T>>>;Internal method to retrieve multiple documents from Firestore, optionally as part of a transaction.
| Name | Description |
| docRefs |
Array<FirebaseFirestore.DocumentReference<T>>
The documents to receive. |
| fieldMask |
FirebaseFirestore.FieldPath[] | null
An optional field mask to apply to this read. |
| requestTag |
string
A unique client-assigned identifier for this request. |
| transactionId |
Uint8Array
The transaction ID to use for this read. |
| Type | Description |
| Promise<Array<DocumentSnapshot<T>>> | A Promise that contains an array with the resulting documents. |
| Name | Description |
| T |
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 |
initializeIfNeeded(requestTag)
initializeIfNeeded(requestTag: string): Promise<void>;Initializes the client if it is not already initialized. All methods in the SDK can be used after this method completes.
| Name | Description |
| requestTag |
string
A unique client-assigned identifier that caused this initialization. A Promise that resolves when the client is initialized. |
| Type | Description |
| Promise<void> |
listCollections()
listCollections(): Promise<CollectionReference[]>;Fetches the root collections that are associated with this Firestore database.
| Type | Description |
| Promise<CollectionReference[]> | {Promise.<Array.
|
registerListener()
registerListener(): void;Registers a listener on this client, incrementing the listener count. This is used to verify that all listeners are unsubscribed when terminate() is called.
| Type | Description |
| void |
request(methodName, request, requestTag, retryCodes)
request<Req, Resp>(methodName: FirestoreUnaryMethod, request: Req, requestTag: string, retryCodes?: number[]): Promise<Resp>;A funnel for all non-streaming API requests, assigning a project ID where necessary within the request options.
| Name | Description |
| methodName |
FirestoreUnaryMethod
Name of the Veneer API endpoint that takes a request and GAX options. |
| request |
Req
The Protobuf request to send. |
| requestTag |
string
A unique client-assigned identifier for this request. |
| retryCodes |
number[]
If provided, a custom list of retry codes. If not provided, retry is based on the behavior as defined in the ServiceConfig. |
| Type | Description |
| Promise<Resp> | A Promise with the request result. |
| Name | Description |
| Req | |
| Resp |
requestStream(methodName, request, requestTag)
requestStream(methodName: FirestoreStreamingMethod, request: {}, requestTag: string): Promise<Duplex>;A funnel for streaming API requests, assigning a project ID where necessary within the request options.
The stream is returned in paused state and needs to be resumed once all listeners are attached.
| Name | Description |
| methodName |
FirestoreStreamingMethod
Name of the streaming Veneer API endpoint that takes a request and GAX options. |
| request |
{}
The Protobuf request to send. |
| requestTag |
string
A unique client-assigned identifier for this request. |
| Type | Description |
| Promise<internal.Duplex> | A Promise with the resulting read-only stream. |
runTransaction(updateFunction, transactionOptions)
runTransaction<T>(updateFunction: (transaction: Transaction) => Promise<T>, transactionOptions?: {
maxAttempts?: number;
}): 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. Transactions are committed once 'updateFunction' resolves and attempted up to five times on failure.
T
| Name | Description |
| updateFunction |
(transaction: Transaction) => Promise<T>
The user function to execute within the transaction context. |
| transactionOptions |
{
maxAttempts?: number;
}
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?: google.protobuf.ITimestamp, encoding?: 'protobufJS'): DocumentSnapshot;Creates a [DocumentSnapshot]DocumentSnapshot or a [QueryDocumentSnapshot]QueryDocumentSnapshot from a firestore.v1.Document proto (or from a resource name for missing documents).
This API is used by Google Cloud Functions and can be called with both 'Proto3 JSON' and 'Protobuf JS' encoded data.
| Name | Description |
| documentName |
string
|
| readTime |
google.protobuf.ITimestamp
A 'Timestamp' proto indicating the time this document was read. |
| encoding |
'protobufJS'
One of 'json' or 'protobufJS'. Applies to both the 'document' Proto and 'readTime'. Defaults to 'protobufJS'. |
| Type | Description |
| DocumentSnapshot | A QueryDocumentSnapshot for existing documents, otherwise a DocumentSnapshot. |
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> |
unregisterListener()
unregisterListener(): void;Unregisters a listener on this client, decrementing the listener count. This is used to verify that all listeners are unsubscribed when terminate() is called.
| Type | Description |
| void |