Constructor

FirestoreClient

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

Methods

anyPathPath

anyPathPath(project, database, document, anyPath) returns String

Returns a fully-qualified any_path resource name string.

Parameter

project

String

database

String

document

String

anyPath

String

Returns

String 

batchGetDocuments

batchGetDocuments(request, options) returns Stream

Gets multiple documents.

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

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

database

string

The database name. In the format: projects/{project_id}/databases/{database_id}.

documents

Array of 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

Optional

Object

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.

This object should have the same structure as DocumentMask

transaction

Optional

string

Reads documents in a transaction.

newTransaction

Optional

Object

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.

This object should have the same structure as TransactionOptions

readTime

Optional

Object

Reads documents as they were at the given time. This may not be older than 60 seconds.

This object should have the same structure as Timestamp

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

Returns

Stream 

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

Example

var firestore = require('firestore.v1beta1');

var client = firestore.v1beta1({
  // optional auth parameters.
});

var formattedDatabase = client.databaseRootPath("[PROJECT]", "[DATABASE]");
var documents = [];
var request = {
    database: formattedDatabase,
    documents: documents
};
client.batchGetDocuments(request).on('data', function(response) {
  // doThingsWith(response)
});

beginTransaction

beginTransaction(request, options, callback) returns Promise

Starts a new transaction.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

database

string

The database name. In the format: projects/{project_id}/databases/{database_id}.

options

Optional

Object

The options for the transaction. Defaults to a read-write transaction.

This object should have the same structure as TransactionOptions

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing BeginTransactionResponse.

Returns

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.

Example

var firestore = require('firestore.v1beta1');

var client = firestore.v1beta1({
  // optional auth parameters.
});

var formattedDatabase = client.databaseRootPath("[PROJECT]", "[DATABASE]");
client.beginTransaction({database: formattedDatabase}).then(function(responses) {
    var response = responses[0];
    // doThingsWith(response)
})
.catch(function(err) {
    console.error(err);
});

commit

commit(request, options, callback) returns Promise

Commits a transaction, while optionally updating documents.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

database

string

The database name. In the format: projects/{project_id}/databases/{database_id}.

writes

Array of Object

The writes to apply.

Always executed atomically and in order.

This object should have the same structure as Write

transaction

Optional

string

If set, applies all writes in this transaction, and commits it.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing CommitResponse.

Returns

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.

Example

var firestore = require('firestore.v1beta1');

var client = firestore.v1beta1({
  // optional auth parameters.
});

var formattedDatabase = client.databaseRootPath("[PROJECT]", "[DATABASE]");
var writes = [];
var request = {
    database: formattedDatabase,
    writes: writes
};
client.commit(request).then(function(responses) {
    var response = responses[0];
    // doThingsWith(response)
})
.catch(function(err) {
    console.error(err);
});

createDocument

createDocument(request, options, callback) returns Promise

Creates a new document.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

parent

string

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

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

Object

The document to create. name must not be set.

This object should have the same structure as Document

mask

Optional

Object

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.

This object should have the same structure as DocumentMask

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Document.

Returns

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.

Example

var firestore = require('firestore.v1beta1');

var client = firestore.v1beta1({
  // optional auth parameters.
});

var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
var collectionId = '';
var documentId = '';
var document = {};
var request = {
    parent: formattedParent,
    collectionId: collectionId,
    documentId: documentId,
    document: document
};
client.createDocument(request).then(function(responses) {
    var response = responses[0];
    // doThingsWith(response)
})
.catch(function(err) {
    console.error(err);
});

databaseRootPath

databaseRootPath(project, database) returns String

Returns a fully-qualified database_root resource name string.

Parameter

project

String

database

String

Returns

String 

deleteDocument

deleteDocument(request, options, callback) returns Promise

Deletes a document.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

name

string

The resource name of the Document to delete. In the format: projects/{project_id}/databases/{database_id}/documents/{document_path}.

currentDocument

Optional

Object

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

This object should have the same structure as Precondition

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error)

The function which will be called with the result of the API call.

Returns

Promise 

  • The promise which resolves when API call finishes. The promise has a method named "cancel" which cancels the ongoing API call.

Example

var firestore = require('firestore.v1beta1');

var client = firestore.v1beta1({
  // optional auth parameters.
});

var formattedName = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
client.deleteDocument({name: formattedName}).catch(function(err) {
    console.error(err);
});