FirestoreClient

FirestoreClient

The Cloud Firestore service.

This service exposes several types of comparable timestamps:

  • create_time - The time at which a document was created. Changes only when a document is deleted, then re-created. Increases in a strict monotonic fashion.
  • update_time - The time at which a document was last updated. Changes every time a document is modified. Does not change when a write results in no modifications. Increases in a strict monotonic fashion.
  • read_time - The time at which a particular state was observed. Used to denote a consistent snapshot of the database or the time at which a Document was observed to not exist.
  • commit_time - The time at which the writes in a transaction were committed. Any read with an equal or greater read_time is guaranteed to see the effects of the transaction.

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.
Deprecated:
  • Use v1/firestore_client instead.

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.v1beta1.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.v1beta1.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 60 seconds.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Stream

An object stream which emits BatchGetDocumentsResponse on 'data' event.

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}.
options google.firestore.v1beta1.TransactionOptions

The options for the transaction. Defaults to a read-write transaction.
options object <optional>

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 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.
options object <optional>

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 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.
document google.firestore.v1beta1.Document

Required. The document to create. name must not be set.
mask google.firestore.v1beta1.DocumentMask

The fields to return. If not set, returns all fields.

If the document has a field that is not present in this mask, that field will not be returned in the response.
options object <optional>

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 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}.
currentDocument google.firestore.v1beta1.Precondition

An optional precondition on the document. The request will fail if this is set and not met by the target document.
options object <optional>

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 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}.
mask google.firestore.v1beta1.DocumentMask

The fields to return. If not set, returns all fields.

If the document has a field that is not present in this mask, that field will not be returned in the response.
transaction Buffer

Reads the document in a transaction.
readTime google.protobuf.Timestamp

Reads the version of the document at the given time. This may not be older than 60 seconds.
options object <optional>

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

listCollectionIds(request, optionsopt) → {Promise}

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
pageSize number

The maximum number of results to return.
pageToken string

A page token. Must be a value from ListCollectionIdsResponse.
options object <optional>

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

listCollectionIdsAsync(request, optionsopt) → {Object}

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
pageSize number

The maximum number of results to return.
pageToken string

A page token. Must be a value from ListCollectionIdsResponse.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Object

An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols.

listCollectionIdsStream(request, optionsopt) → {Stream}

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
pageSize number

The maximum number of results to return.
pageToken string

A page token. Must be a value from ListCollectionIdsResponse.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Stream

An object stream which emits an object representing string on 'data' event.
See:

listDocuments(request, optionsopt) → {Promise}

Lists documents.

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.
mask google.firestore.v1beta1.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.
readTime google.protobuf.Timestamp

Reads documents as they were at the given time. This may not be older than 60 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.
options object <optional>

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

listDocumentsAsync(request, optionsopt) → {Object}

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.
mask google.firestore.v1beta1.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.
readTime google.protobuf.Timestamp

Reads documents as they were at the given time. This may not be older than 60 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.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Object

An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols.

listDocumentsStream(request, optionsopt) → {Stream}

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.
mask google.firestore.v1beta1.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.
readTime google.protobuf.Timestamp

Reads documents as they were at the given time. This may not be older than 60 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.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Stream

An object stream which emits an object representing Document on 'data' event.
See:

listen(optionsopt) → {Stream}

Listens to changes.

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.

rollback(request, optionsopt) → {Promise}

Rolls back a 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}.
transaction Buffer

Required. The transaction to roll back.
options object <optional>

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 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
structuredQuery google.firestore.v1beta1.StructuredQuery

A structured query.
transaction Buffer

Reads documents in a transaction.
newTransaction google.firestore.v1beta1.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 60 seconds.
options object <optional>

Call options. See CallOptions for more details.
Returns:
Type Description
Stream

An object stream which emits RunQueryResponse on 'data' event.

updateDocument(request, optionsopt) → {Promise}

Updates or inserts a document.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Description
document google.firestore.v1beta1.Document

Required. The updated document. Creates the document if it does not already exist.
updateMask google.firestore.v1beta1.DocumentMask

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.
mask google.firestore.v1beta1.DocumentMask

The fields to return. If not set, returns all fields.

If the document has a field that is not present in this mask, that field will not be returned in the response.
currentDocument google.firestore.v1beta1.Precondition

An optional precondition on the document. The request will fail if this is set and not met by the target document.
options object <optional>

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

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.