FirestoreClient

The Cloud Firestore service.

Cloud Firestore is a fast, fully managed, serverless, cloud-native NoSQL document database that simplifies storing, syncing, and querying data for your mobile, web, and IoT apps at global scale. Its client libraries provide live synchronization and offline support, while its security features and integrations with Firebase and Google Cloud Platform accelerate building truly serverless apps.

Constructor

new FirestoreClient(optionsopt, gaxInstanceopt)

Construct an instance of FirestoreClient.

Parameters:

Name Type Attributes Description

options

object

The configuration object. The options accepted by the constructor are described in detail in this document. The common options are:

Properties

Name Type Attributes Description

credentials

object

Credentials object.

Properties

Name	Type	Attributes	Description
`client_email`	string	<optional>
`private_key`	string	<optional>

email

string

Account email address. Required when using a .pem or .p12 keyFilename.

keyFilename

string

Full path to the a .json, .pem, or .p12 key downloaded from the Google Developers Console. If you provide a path to a JSON file, the projectId option below is not necessary. NOTE: .pem and .p12 require you to specify options.email as well.

port

number

The port on which to connect to the remote host.

projectId

string

The project ID from the Google Developer's Console, e.g. 'grape-spaceship-123'. We will also check the environment variable GCLOUD_PROJECT for your project ID. If your app is running in an environment which supports Application Default Credentials, your project ID will be detected automatically.

apiEndpoint

string

The domain name of the API remote host.

clientConfig

gax.ClientConfig

Client configuration override. Follows the structure of gapicConfig.

fallback

boolean | "rest"

Use HTTP fallback mode. Pass "rest" to use HTTP/1.1 REST API instead of gRPC. For more information, please check the documentation.

gaxInstance

gax

loaded instance of google-gax. Useful if you need to avoid loading the default gRPC version and want to use the fallback HTTP implementation. Load only fallback version and pass it to the constructor: const gax = require('google-gax/build/src/fallback'); // avoids loading google-gax with gRPC const client = new FirestoreClient({fallback: 'rest'}, gax);

Members

apiEndpoint

The DNS address for this API service - same as servicePath(), exists for compatibility reasons.

port

The port for this API service.

scopes

The scopes needed to make gRPC calls for every method defined in this service.

servicePath

The DNS address for this API service.

Methods

batchGetDocuments(request, optionsopt) → {Stream}

Gets multiple documents.

Documents returned by this method are not guaranteed to be returned in the same order that they were requested.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`database`	string	Required. The database name. In the format: `projects/{project_id}/databases/{database_id}`.
`documents`	Array.<string>	The names of the documents to retrieve. In the format: `projects/{project_id}/databases/{database_id}/documents/{document_path}`. The request will fail if any of the document is not a child resource of the given `database`. Duplicate names will be elided.
`mask`	google.firestore.v1.DocumentMask	The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response.
`transaction`	Buffer	Reads documents in a transaction.
`newTransaction`	google.firestore.v1.TransactionOptions	Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits BatchGetDocumentsResponse on 'data' event. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.batch_get_documents.js

region_tag:firestore_v1_generated_Firestore_BatchGetDocuments_async

close() → {Promise}

Terminate the gRPC channel and close the client.

The client will no longer be usable and all future behavior is undefined.

Returns:

Type	Description
Promise	A promise that resolves when the client is closed.

getLocation(request, optionsopt) → {Promise}

Gets information about a location.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`name`	string	Resource name for the location.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Promise	The promise which resolves to an array. The first element of the array is an object representing Location. Please see the documentation for more details and examples.

Example

```
const [response] = await client.getLocation(request);
```

getProjectId() → {Promise}

Return the project ID used by this class.

Returns:

Type	Description
Promise	A promise that resolves to string containing the project ID.

initialize() → {Promise}

Initialize the client. Performs asynchronous operations (such as authentication) and prepares the client. This function will be called automatically when any class method is called for the first time, but if you need to initialize it before calling an actual method, feel free to call initialize() directly.

You can await on this method if you want to make sure the client is initialized.

Returns:

Type	Description
Promise	A promise that resolves to an authenticated service stub.

listCollectionIdsAsync(request, optionsopt) → {Object}

Equivalent to listCollectionIds, but returns an iterable object.

for-await-of syntax is used with the iterable to get response elements on-demand.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent document. In the format: `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`pageSize`	number	The maximum number of results to return.
`pageToken`	string	A page token. Must be a value from ListCollectionIdsResponse.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Object	An iterable Object that allows async iteration. When you iterate the returned iterable, each element will be an object representing string. The API will be called under the hood as needed, once per the page, so you can stop the iteration when you don't need more results. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.list_collection_ids.js

region_tag:firestore_v1_generated_Firestore_ListCollectionIds_async

listCollectionIdsStream(request, optionsopt) → {Stream}

Equivalent to method.name.toCamelCase(), but returns a NodeJS Stream object.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent document. In the format: `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`pageSize`	number	The maximum number of results to return.
`pageToken`	string	A page token. Must be a value from ListCollectionIdsResponse.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits an object representing string on 'data' event. The client library will perform auto-pagination by default: it will call the API as many times as needed. Note that it can affect your quota. We recommend using `listCollectionIdsAsync()` method described below for async iteration which you can stop as needed. Please see the documentation for more details and examples.

listDocumentsAsync(request, optionsopt) → {Object}

Equivalent to listDocuments, but returns an iterable object.

for-await-of syntax is used with the iterable to get response elements on-demand.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Attributes	Description
`parent`	string		Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents` or `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents` or `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`collectionId`	string	<optional>	Optional. The collection ID, relative to `parent`, to list. For example: `chatrooms` or `messages`. This is optional, and when not provided, Firestore will list documents from all collections under the provided `parent`.
`pageSize`	number	<optional>	Optional. The maximum number of documents to return in a single response. Firestore may return fewer than this value.
`pageToken`	string	<optional>	Optional. A page token, received from a previous `ListDocuments` response. Provide this to retrieve the subsequent page. When paginating, all other parameters (with the exception of `page_size`) must match the values set in the request that generated the page token.
`orderBy`	string	<optional>	Optional. The optional ordering of the documents to return. For example: `priority desc, __name__ desc`. This mirrors the `ORDER BY` used in Firestore queries but in a string representation. When absent, documents are ordered based on `__name__ ASC`.
`mask`	google.firestore.v1.DocumentMask	<optional>	Optional. The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response.
`transaction`	Buffer		Perform the read as part of an already active transaction.
`readTime`	google.protobuf.Timestamp		Perform the read at the provided time. This may not be older than 270 seconds.
`showMissing`	boolean		If the list should show missing documents. A document is missing if it does not exist, but there are sub-documents nested underneath it. When true, such missing documents will be returned with a key but will not have fields, `create_time`, or `update_time` set. Requests with `show_missing` may not specify `where` or `order_by`.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Object	An iterable Object that allows async iteration. When you iterate the returned iterable, each element will be an object representing Document. The API will be called under the hood as needed, once per the page, so you can stop the iteration when you don't need more results. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.list_documents.js

region_tag:firestore_v1_generated_Firestore_ListDocuments_async

listDocumentsStream(request, optionsopt) → {Stream}

Equivalent to method.name.toCamelCase(), but returns a NodeJS Stream object.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Attributes	Description
`parent`	string		Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents` or `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents` or `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`collectionId`	string	<optional>	Optional. The collection ID, relative to `parent`, to list. For example: `chatrooms` or `messages`. This is optional, and when not provided, Firestore will list documents from all collections under the provided `parent`.
`pageSize`	number	<optional>	Optional. The maximum number of documents to return in a single response. Firestore may return fewer than this value.
`pageToken`	string	<optional>	Optional. A page token, received from a previous `ListDocuments` response. Provide this to retrieve the subsequent page. When paginating, all other parameters (with the exception of `page_size`) must match the values set in the request that generated the page token.
`orderBy`	string	<optional>	Optional. The optional ordering of the documents to return. For example: `priority desc, __name__ desc`. This mirrors the `ORDER BY` used in Firestore queries but in a string representation. When absent, documents are ordered based on `__name__ ASC`.
`mask`	google.firestore.v1.DocumentMask	<optional>	Optional. The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response.
`transaction`	Buffer		Perform the read as part of an already active transaction.
`readTime`	google.protobuf.Timestamp		Perform the read at the provided time. This may not be older than 270 seconds.
`showMissing`	boolean		If the list should show missing documents. A document is missing if it does not exist, but there are sub-documents nested underneath it. When true, such missing documents will be returned with a key but will not have fields, `create_time`, or `update_time` set. Requests with `show_missing` may not specify `where` or `order_by`.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits an object representing Document on 'data' event. The client library will perform auto-pagination by default: it will call the API as many times as needed. Note that it can affect your quota. We recommend using `listDocumentsAsync()` method described below for async iteration which you can stop as needed. Please see the documentation for more details and examples.

listLocationsAsync(request, optionsopt) → {Object}

Lists information about the supported locations for this service. Returns an iterable object.

for-await-of syntax is used with the iterable to get response elements on-demand.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`name`	string	The resource that owns the locations collection, if applicable.
`filter`	string	The standard list filter.
`pageSize`	number	The standard list page size.
`pageToken`	string	The standard list page token.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Object	An iterable Object that allows async iteration. When you iterate the returned iterable, each element will be an object representing Location. The API will be called under the hood as needed, once per the page, so you can stop the iteration when you don't need more results. Please see the documentation for more details and examples.

Example

```
const iterable = client.listLocationsAsync(request);
for await (const response of iterable) {
  // process response
}
```

listen(optionsopt) → {Stream}

Listens to changes. This method is only available via the gRPC API (not REST).

Parameters:

Name	Type	Attributes	Description
`options`	object	<optional>	Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which is both readable and writable. It accepts objects representing ListenRequest for write() method, and will emit objects representing ListenResponse on 'data' event asynchronously. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.listen.js

region_tag:firestore_v1_generated_Firestore_Listen_async

partitionQueryAsync(request, optionsopt) → {Object}

Equivalent to partitionQuery, but returns an iterable object.

for-await-of syntax is used with the iterable to get response elements on-demand.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents`. Document resource names are not supported; only database resource names can be specified.
`structuredQuery`	google.firestore.v1.StructuredQuery	A structured query. Query must specify collection with all descendants and be ordered by name ascending. Other filters, order bys, limits, offsets, and start/end cursors are not supported.
`partitionCount`	number	The desired maximum number of partition points. The partitions may be returned across multiple pages of results. The number must be positive. The actual number of partitions returned may be fewer. For example, this may be set to one fewer than the number of parallel queries to be run, or in running a data pipeline job, one fewer than the number of workers or compute instances available.
`pageToken`	string	The `next_page_token` value returned from a previous call to PartitionQuery that may be used to get an additional set of results. There are no ordering guarantees between sets of results. Thus, using multiple sets of results will require merging the different result sets. For example, two subsequent calls using a page_token may return: cursor B, cursor M, cursor Q cursor A, cursor U, cursor W To obtain a complete result set ordered with respect to the results of the query supplied to PartitionQuery, the results sets should be merged: cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W
`pageSize`	number	The maximum number of partitions to return in this call, subject to `partition_count`. For example, if `partition_count` = 10 and `page_size` = 8, the first call to PartitionQuery will return up to 8 partitions and a `next_page_token` if more results exist. A second call to PartitionQuery will return up to 2 partitions, to complete the total of 10 specified in `partition_count`.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Object	An iterable Object that allows async iteration. When you iterate the returned iterable, each element will be an object representing Cursor. The API will be called under the hood as needed, once per the page, so you can stop the iteration when you don't need more results. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.partition_query.js

region_tag:firestore_v1_generated_Firestore_PartitionQuery_async

partitionQueryStream(request, optionsopt) → {Stream}

Equivalent to method.name.toCamelCase(), but returns a NodeJS Stream object.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents`. Document resource names are not supported; only database resource names can be specified.
`structuredQuery`	google.firestore.v1.StructuredQuery	A structured query. Query must specify collection with all descendants and be ordered by name ascending. Other filters, order bys, limits, offsets, and start/end cursors are not supported.
`partitionCount`	number	The desired maximum number of partition points. The partitions may be returned across multiple pages of results. The number must be positive. The actual number of partitions returned may be fewer. For example, this may be set to one fewer than the number of parallel queries to be run, or in running a data pipeline job, one fewer than the number of workers or compute instances available.
`pageToken`	string	The `next_page_token` value returned from a previous call to PartitionQuery that may be used to get an additional set of results. There are no ordering guarantees between sets of results. Thus, using multiple sets of results will require merging the different result sets. For example, two subsequent calls using a page_token may return: cursor B, cursor M, cursor Q cursor A, cursor U, cursor W To obtain a complete result set ordered with respect to the results of the query supplied to PartitionQuery, the results sets should be merged: cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W
`pageSize`	number	The maximum number of partitions to return in this call, subject to `partition_count`. For example, if `partition_count` = 10 and `page_size` = 8, the first call to PartitionQuery will return up to 8 partitions and a `next_page_token` if more results exist. A second call to PartitionQuery will return up to 2 partitions, to complete the total of 10 specified in `partition_count`.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits an object representing Cursor on 'data' event. The client library will perform auto-pagination by default: it will call the API as many times as needed. Note that it can affect your quota. We recommend using `partitionQueryAsync()` method described below for async iteration which you can stop as needed. Please see the documentation for more details and examples.

runAggregationQuery(request, optionsopt) → {Stream}

Runs an aggregation query.

Rather than producing Document results like Firestore.RunQuery, this API allows running an aggregation to produce a series of AggregationResult server-side.

High-Level Example:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents` or `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents` or `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`structuredAggregationQuery`	google.firestore.v1.StructuredAggregationQuery	An aggregation query.
`transaction`	Buffer	Run the aggregation within an already active transaction. The value here is the opaque transaction ID to execute the query in.
`newTransaction`	google.firestore.v1.TransactionOptions	Starts a new transaction as part of the query, defaulting to read-only. The new transaction ID will be returned as the first response in the stream.
`readTime`	google.protobuf.Timestamp	Executes the query at the given timestamp. Requires: Cannot be more than 270 seconds in the past.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits RunAggregationQueryResponse on 'data' event. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.run_aggregation_query.js

region_tag:firestore_v1_generated_Firestore_RunAggregationQuery_async

runQuery(request, optionsopt) → {Stream}

Runs a query.

Parameters:

Name Type Attributes Description

request

Object

The request object that will be sent.

Properties

Name	Type	Description
`parent`	string	Required. The parent resource name. In the format: `projects/{project_id}/databases/{database_id}/documents` or `projects/{project_id}/databases/{database_id}/documents/{document_path}`. For example: `projects/my-project/databases/my-database/documents` or `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
`structuredQuery`	google.firestore.v1.StructuredQuery	A structured query.
`transaction`	Buffer	Run the query within an already active transaction. The value here is the opaque transaction ID to execute the query in.
`newTransaction`	google.firestore.v1.TransactionOptions	Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream.
`readTime`	google.protobuf.Timestamp	Reads documents as they were at the given time. This may not be older than 270 seconds.

options

object

Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which emits RunQueryResponse on 'data' event. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.run_query.js

region_tag:firestore_v1_generated_Firestore_RunQuery_async

write(optionsopt) → {Stream}

Streams batches of document updates and deletes, in order. This method is only available via the gRPC API (not REST).

Parameters:

Name	Type	Attributes	Description
`options`	object	<optional>	Call options. See CallOptions for more details.

Returns:

Type	Description
Stream	An object stream which is both readable and writable. It accepts objects representing WriteRequest for write() method, and will emit objects representing WriteResponse on 'data' event asynchronously. Please see the documentation for more details and examples.

Example

include:samples/generated/v1/firestore.write.js

region_tag:firestore_v1_generated_Firestore_Write_async