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 (GCP) accelerate
building truly serverless apps.
Constructor
new FirestoreClient(optionsopt)
Construct an instance of FirestoreClient.
Parameters:
Name
Type
Attributes
Description
options
object
<optional>
The configuration object. See the subsequent
parameters for more details.
Properties
Name
Type
Attributes
Description
credentials
object
<optional>
Credentials object.
Properties
Name
Type
Attributes
Description
client_email
string
<optional>
private_key
string
<optional>
email
string
<optional>
Account email address. Required when
using a .pem or .p12 keyFilename.
keyFilename
string
<optional>
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
<optional>
The port on which to connect to
the remote host.
projectId
string
<optional>
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
<optional>
The domain name of the
API remote host.
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.
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.
The BatchWrite method does not apply the write operations atomically
and can apply them out of order. Method does not allow more than one write
per document. Each write succeeds or fails independently. See the
BatchWriteResponse for the success status of each write.
If you require an atomically applied set of writes, use
Commit instead.
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}.
writes
Array.<number>
The writes to apply.
Method does not apply writes atomically and does not guarantee ordering.
Each write succeeds or fails independently. You cannot write to the same
document more than once per request.
The promise which resolves to an array.
The first element of the array is an object representing BatchWriteResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
beginTransaction(request, optionsopt) → {Promise}
Starts a new transaction.
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}.
The promise which resolves to an array.
The first element of the array is an object representing BeginTransactionResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
close()
Terminate the GRPC channel and close the client.
The client will no longer be usable and all future behavior is undefined.
commit(request, optionsopt) → {Promise}
Commits a transaction, while optionally updating documents.
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}.
writes
Array.<number>
The writes to apply.
Always executed atomically and in order.
transaction
Buffer
If set, applies all writes in this transaction, and commits it.
The promise which resolves to an array.
The first element of the array is an object representing CommitResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
createDocument(request, optionsopt) → {Promise}
Creates a new document.
Parameters:
Name
Type
Attributes
Description
request
Object
The request object that will be sent.
Properties
Name
Type
Description
parent
string
Required. The parent resource. For example:
projects/{project_id}/databases/{database_id}/documents or
projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}
collectionId
string
Required. The collection ID, relative to parent, to list. For example: chatrooms.
documentId
string
The client-assigned document ID to use for this document.
Optional. If not specified, an ID will be assigned by the service.
The promise which resolves to an array.
The first element of the array is an object representing Document.
The promise has a method named "cancel" which cancels the ongoing API call.
deleteDocument(request, optionsopt) → {Promise}
Deletes a document.
Parameters:
Name
Type
Attributes
Description
request
Object
The request object that will be sent.
Properties
Name
Type
Description
name
string
Required. The resource name of the Document to delete. In the format:
projects/{project_id}/databases/{database_id}/documents/{document_path}.
The promise which resolves to an array.
The first element of the array is an object representing Empty.
The promise has a method named "cancel" which cancels the ongoing API call.
getDocument(request, optionsopt) → {Promise}
Gets a single document.
Parameters:
Name
Type
Attributes
Description
request
Object
The request object that will be sent.
Properties
Name
Type
Description
name
string
Required. The resource name of the Document to get. In the format:
projects/{project_id}/databases/{database_id}/documents/{document_path}.
The promise which resolves to an array.
The first element of the array is an object representing Document.
The promise has a method named "cancel" which cancels the ongoing API call.
getProjectId(callback)
Return the project ID used by this class.
Parameters:
Name
Type
Description
callback
function
the callback to
be called with the current 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.
Lists all the collection IDs underneath a document.
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
The promise which resolves to an array.
The first element of the array is Array of string.
The client library support auto-pagination by default: it will call the API as many
times as needed and will merge results from all the pages into this array.
When autoPaginate: false is specified through options, the array has three elements.
The first element is Array of string that corresponds to
the one page received from the API server.
If the second element is not null it contains the request object of type ListCollectionIdsRequest
that can be used to obtain the next page of the results.
If it is null, the next page does not exist.
The third element contains the raw response received from the API server. Its type is
ListCollectionIdsResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
Equivalent to listCollectionIds, but returns an iterable object.
for-await-of syntax is used with the iterable to recursively get response element 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
Equivalent to listCollectionIds, but returns a NodeJS Stream object.
This fetches the paged responses for listCollectionIds continuously
and invokes the callback registered for 'data' event for each element in the
responses.
The returned object has 'end' method when no more elements are required.
autoPaginate option will be ignored.
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
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
Required. The collection ID, relative to parent, to list. For example: chatrooms
or messages.
pageSize
number
The maximum number of documents to return.
pageToken
string
The next_page_token value returned from a previous List request, if any.
orderBy
string
The order to sort results by. For example: priority desc, name.
Reads documents as they were at the given time.
This may not be older than 270 seconds.
showMissing
boolean
If the list should show missing documents. A missing document is a
document that does not exist but has sub-documents. These documents will
be returned with a key but will not have fields, Document.create_time,
or Document.update_time set.
Requests with show_missing may not specify where or
order_by.
The promise which resolves to an array.
The first element of the array is Array of Document.
The client library support auto-pagination by default: it will call the API as many
times as needed and will merge results from all the pages into this array.
When autoPaginate: false is specified through options, the array has three elements.
The first element is Array of Document that corresponds to
the one page received from the API server.
If the second element is not null it contains the request object of type ListDocumentsRequest
that can be used to obtain the next page of the results.
If it is null, the next page does not exist.
The third element contains the raw response received from the API server. Its type is
ListDocumentsResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
Equivalent to listDocuments, but returns an iterable object.
for-await-of syntax is used with the iterable to recursively get response element 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 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
Required. The collection ID, relative to parent, to list. For example: chatrooms
or messages.
pageSize
number
The maximum number of documents to return.
pageToken
string
The next_page_token value returned from a previous List request, if any.
orderBy
string
The order to sort results by. For example: priority desc, name.
Reads documents as they were at the given time.
This may not be older than 270 seconds.
showMissing
boolean
If the list should show missing documents. A missing document is a
document that does not exist but has sub-documents. These documents will
be returned with a key but will not have fields, Document.create_time,
or Document.update_time set.
Requests with show_missing may not specify where or
order_by.
Equivalent to listDocuments, but returns a NodeJS Stream object.
This fetches the paged responses for listDocuments continuously
and invokes the callback registered for 'data' event for each element in the
responses.
The returned object has 'end' method when no more elements are required.
autoPaginate option will be ignored.
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
collectionId
string
Required. The collection ID, relative to parent, to list. For example: chatrooms
or messages.
pageSize
number
The maximum number of documents to return.
pageToken
string
The next_page_token value returned from a previous List request, if any.
orderBy
string
The order to sort results by. For example: priority desc, name.
Reads documents as they were at the given time.
This may not be older than 270 seconds.
showMissing
boolean
If the list should show missing documents. A missing document is a
document that does not exist but has sub-documents. These documents will
be returned with a key but will not have fields, Document.create_time,
or Document.update_time set.
Requests with show_missing may not specify where or
order_by.
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.
partitionQuery(request, optionsopt) → {Promise}
Partitions a query by returning partition cursors that can be used to run
the query in parallel. The returned partition cursors are split points that
can be used by RunQuery as starting/end points for the query results.
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.
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.
The promise which resolves to an array.
The first element of the array is Array of Cursor.
The client library support auto-pagination by default: it will call the API as many
times as needed and will merge results from all the pages into this array.
When autoPaginate: false is specified through options, the array has three elements.
The first element is Array of Cursor that corresponds to
the one page received from the API server.
If the second element is not null it contains the request object of type PartitionQueryRequest
that can be used to obtain the next page of the results.
If it is null, the next page does not exist.
The third element contains the raw response received from the API server. Its type is
PartitionQueryResponse.
The promise has a method named "cancel" which cancels the ongoing API call.
Equivalent to partitionQuery, but returns an iterable object.
for-await-of syntax is used with the iterable to recursively get response element 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.
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.
Equivalent to partitionQuery, but returns a NodeJS Stream object.
This fetches the paged responses for partitionQuery continuously
and invokes the callback registered for 'data' event for each element in the
responses.
The returned object has 'end' method when no more elements are required.
autoPaginate option will be ignored.
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.
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.
The promise which resolves to an array.
The first element of the array is an object representing Empty.
The promise has a method named "cancel" which cancels the ongoing API call.
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
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.
The fields to update.
None of the field paths in the mask may contain a reserved name.
If the document exists on the server and has fields not referenced in the
mask, they are left unchanged.
Fields referenced in the mask, but not present in the input document, are
deleted from the document on the server.
The promise which resolves to an array.
The first element of the array is an object representing Document.
The promise has a method named "cancel" which cancels the ongoing API call.
write(optionsopt) → {Stream}
Streams batches of document updates and deletes, in order.
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.