Class Firestore (4.9.8)

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

Parameter

Name	Description
settings	`firestore.Settings` [Configuration object](#/docs).

Properties

_serializer

  _serializer 
 : 
  
 Serializer 
  
 | 
  
 null 
 ;

The serializer to use for the Protobuf transformation.

Property Value

Type	Description
Serializer \| null

_settings

  _settings 
 : 
  
 firestore 
 . 
 Settings 
 ;

The configuration options for the GAPIC client.

Property Value

Type	Description
firestore.Settings

formattedName

  get 
  
 formattedName 
 () 
 : 
  
 string 
 ;

Returns the root path of the database. Validates that initializeIfNeeded() was called before.

Property Value

Type	Description
string

projectId

  get 
  
 projectId 
 () 
 : 
  
 string 
 ;

Returns the Project ID for this Firestore instance. Validates that initializeIfNeeded() was called before.

Property Value

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.

Returns

Type	Description
void

_getAllDescendants(ref)

  _getAllDescendants 
 ( 
 ref 
 : 
  
 CollectionReference 
  
 | 
  
 DocumentReference 
 ) 
 : 
  
 NodeJS 
 . 
 ReadableStream 
 ;

Retrieves all descendant documents nested under the provided reference.

{Stream

Parameter

Name	Description
ref	`CollectionReference \| DocumentReference`

Returns

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.

Returns

Type	Description
void

batch()

  batch 
 () 
 : 
  
 WriteBatch 
 ;

Creates a [WriteBatch] WriteBatch , used for performing multiple writes as a single atomic operation.

Returns

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

Parameter

Name	Description
options	`firestore.BulkWriterOptions` BulkWriter options.

Returns

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.

Parameter

Name	Description
name	`string`

Returns

Type	Description
BundleBuilder

collection(collectionPath)

  collection 
 ( 
 collectionPath 
 : 
  
 string 
 ) 
 : 
  
 CollectionReference 
 ;

Gets a [CollectionReference] CollectionReference instance that refers to the collection at the specified path.

Parameter

Name	Description
collectionPath	`string` A slash-separated path to a collection.

Returns

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.

Parameter

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.

Returns

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.

Parameter

Name	Description
documentPath	`string` A slash-separated path to a document.

Returns

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.

Parameters

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.

Returns

Type	Description
Promise < Array < DocumentSnapshot <T>>>	A Promise that contains an array with the resulting documents.

Type Parameter

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.

Parameter

Name	Description
documentRefsOrReadOptions	`Array < FirebaseFirestore.DocumentReference <T> \| FirebaseFirestore.ReadOptions >` The `DocumentReferences` to receive, followed by an optional field mask.

Returns

Type	Description
Promise < Array < DocumentSnapshot <T>>>	{Promise<Array.

Type Parameter

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.

Parameter

Name	Description
requestTag	`string` A unique client-assigned identifier that caused this initialization. A Promise that resolves when the client is initialized.

Returns

Type	Description
Promise <void>

listCollections()

  listCollections 
 () 
 : 
  
 Promise<CollectionReference 
 []>;

Fetches the root collections that are associated with this Firestore database.

Returns

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.

Returns

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.

Parameters

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.

Returns

Type	Description
Promise <Resp>	A Promise with the request result.

Type Parameters

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.

Parameters

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.

Returns

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.

Parameters

Name	Description
updateFunction	`(transaction: Transaction ) => Promise <T>` The user function to execute within the transaction context.
transactionOptions	`{ maxAttempts?: number; }` Transaction options.

Returns

Type	Description
Promise <T>	{Promise

Type Parameter

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.

Parameter

Name	Description
settings	`firestore.Settings` The settings to use for all Firestore operations.

Returns

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.

Parameters

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

Returns

Type	Description
DocumentSnapshot	A QueryDocumentSnapshot for existing documents, otherwise a DocumentSnapshot.

snapshot_(documentName, readTime, encoding)

  snapshot_ 
 ( 
 documentName 
 : 
  
 string 
 , 
  
 readTime 
 : 
  
 string 
 , 
  
 encoding 
 : 
  
 'json' 
 ) 
 : 
  
 DocumentSnapshot 
 ;

Parameters

Name	Description
documentName	`string`
readTime	`string`
encoding	`'json'`

Returns

Type	Description
DocumentSnapshot

snapshot_(document, readTime, encoding)

  snapshot_ 
 ( 
 document 
 : 
  
 api 
 . 
 IDocument 
 , 
  
 readTime 
 : 
  
 google 
 . 
 protobuf 
 . 
 ITimestamp 
 , 
  
 encoding 
 ?: 
  
 'protobufJS' 
 ) 
 : 
  
 QueryDocumentSnapshot 
 ;

Parameters

Name	Description
document	`api.IDocument`
readTime	`google.protobuf.ITimestamp`
encoding	`'protobufJS'`

Returns

Type	Description
QueryDocumentSnapshot

snapshot_(document, readTime, encoding)

  snapshot_ 
 ( 
 document 
 : 
  
 { 
  
 [ 
 k 
 : 
  
 string 
 ] 
 : 
  
 unknown 
 ; 
  
 }, 
  
 readTime 
 : 
  
 string 
 , 
  
 encoding 
 : 
  
 'json' 
 ) 
 : 
  
 QueryDocumentSnapshot 
 ;

Parameters

Name	Description
document	`{ [k: string]: unknown; }`
readTime	`string`
encoding	`'json'`

Returns

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.

Returns

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.

Returns

Type	Description
void

Class Firestore (4.9.8) Stay organized with collections Save and categorize content based on your preferences.

Package

Constructors

(constructor)(settings)

Properties

_serializer

_settings

formattedName

projectId

Methods

_decrementBulkWritersCount()

_getAllDescendants(ref)

_incrementBulkWritersCount()

batch()

bulkWriter(options)

bundle(name)

collection(collectionPath)

collectionGroup(collectionId)

doc(documentPath)

getAll_(docRefs, fieldMask, requestTag, transactionId)

getAll(documentRefsOrReadOptions)

initializeIfNeeded(requestTag)

listCollections()

registerListener()

request(methodName, request, requestTag, retryCodes)

requestStream(methodName, request, requestTag)

runTransaction(updateFunction, transactionOptions)

settings(settings)

snapshot_(documentName, readTime, encoding)

snapshot_(documentName, readTime, encoding)

snapshot_(document, readTime, encoding)

snapshot_(document, readTime, encoding)

terminate()

unregisterListener()

Class Firestore (4.9.8)