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.

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.

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.

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.

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.

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);
});

documentPathPath

documentPathPath(project, database, documentPath) returns String

Returns a fully-qualified document_path resource name string.

Parameter

project

String

database

String

documentPath

String

Returns

String 

documentRootPath

documentRootPath(project, database) returns String

Returns a fully-qualified document_root resource name string.

Parameter

project

String

database

String

Returns

String 

getDocument

getDocument(request, options, callback) returns Promise

Gets a single document.

Parameter

request

Object

The request object that will be sent.

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 formattedName = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
client.getDocument({name: formattedName}).then(function(responses) {
    var response = responses[0];
    // doThingsWith(response)
})
.catch(function(err) {
    console.error(err);
});

getProjectId

getProjectId(callback)

Get the project ID used by this class.

Parameter

callback

function(Error, string)

the callback to be called with the current project Id.

listCollectionIds

listCollectionIds(request, options, callback) returns Promise

Lists all the collection IDs underneath a document.

Parameter

request

Object

The request object that will be sent.

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 Array, nullable Object, nullable Object)

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

The second parameter to the callback is Array of string.

When autoPaginate: false is specified through options, it contains the result in a single response. If the response indicates the next page exists, the third parameter is set to be used for the next request object. The fourth parameter keeps the raw response object of an object representing ListCollectionIdsResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is Array of string.

    When autoPaginate: false is specified through options, the array has three elements. The first element is Array of string in a single response. The second element is the next request object if the response indicates the next page exists, or null. The third element is an object representing ListCollectionIdsResponse.

    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.
});

// Iterate over all elements.
var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");

client.listCollectionIds({parent: formattedParent}).then(function(responses) {
    var resources = responses[0];
    for (var i = 0; i < resources.length; ++i) {
        // doThingsWith(resources[i])
    }
})
.catch(function(err) {
    console.error(err);
});

// Or obtain the paged response.
var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");


var options = {autoPaginate: false};
function callback(responses) {
    // The actual resources in a response.
    var resources = responses[0];
    // The next request if the response shows there's more responses.
    var nextRequest = responses[1];
    // The actual response object, if necessary.
    // var rawResponse = responses[2];
    for (var i = 0; i < resources.length; ++i) {
        // doThingsWith(resources[i]);
    }
    if (nextRequest) {
        // Fetch the next page.
        return client.listCollectionIds(nextRequest, options).then(callback);
    }
}
client.listCollectionIds({parent: formattedParent}, options)
    .then(callback)
    .catch(function(err) {
        console.error(err);
    });

listCollectionIdsStream

listCollectionIdsStream(request, options) returns 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.

Parameter

request

Object

The request object that will be sent.

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.

See also
https://nodejs.org/api/stream.html
Returns

Stream 

An object stream which emits a string on 'data' event.

Example

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

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

var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
client.listCollectionIdsStream({parent: formattedParent})
.on('data', function(element) {
    // doThingsWith(element)
}).on('error', function(err) {
    console.log(err);
});

listDocuments

listDocuments(request, options, callback) returns Promise

Lists documents.

Parameter

request

Object

The request object that will be sent.

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 Array, nullable Object, nullable Object)

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

The second parameter to the callback is Array of Document.

When autoPaginate: false is specified through options, it contains the result in a single response. If the response indicates the next page exists, the third parameter is set to be used for the next request object. The fourth parameter keeps the raw response object of an object representing ListDocumentsResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is Array of Document.

    When autoPaginate: false is specified through options, the array has three elements. The first element is Array of Document in a single response. The second element is the next request object if the response indicates the next page exists, or null. The third element is an object representing ListDocumentsResponse.

    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.
});

// Iterate over all elements.
var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
var collectionId = '';
var request = {
    parent: formattedParent,
    collectionId: collectionId
};

client.listDocuments(request).then(function(responses) {
    var resources = responses[0];
    for (var i = 0; i < resources.length; ++i) {
        // doThingsWith(resources[i])
    }
})
.catch(function(err) {
    console.error(err);
});

// Or obtain the paged response.
var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
var collectionId = '';
var request = {
    parent: formattedParent,
    collectionId: collectionId
};


var options = {autoPaginate: false};
function callback(responses) {
    // The actual resources in a response.
    var resources = responses[0];
    // The next request if the response shows there's more responses.
    var nextRequest = responses[1];
    // The actual response object, if necessary.
    // var rawResponse = responses[2];
    for (var i = 0; i < resources.length; ++i) {
        // doThingsWith(resources[i]);
    }
    if (nextRequest) {
        // Fetch the next page.
        return client.listDocuments(nextRequest, options).then(callback);
    }
}
client.listDocuments(request, options)
    .then(callback)
    .catch(function(err) {
        console.error(err);
    });

listDocumentsStream

listDocumentsStream(request, options) returns 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.

Parameter

request

Object

The request object that will be sent.

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.

See also
https://nodejs.org/api/stream.html
Returns

Stream 

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

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 request = {
    parent: formattedParent,
    collectionId: collectionId
};
client.listDocumentsStream(request)
.on('data', function(element) {
    // doThingsWith(element)
}).on('error', function(err) {
    console.log(err);
});

listen

listen(options) returns Stream

Listens to changes.

Parameter

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 is both readable and writable. It accepts objects representing ListenRequest for write() method, and will emit objects representing ListenResponse on 'data' event asynchronously.

Example

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

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

var stream = client.listen().on('data', function(response) {
    // doThingsWith(response)
});
var formattedDatabase = client.databaseRootPath("[PROJECT]", "[DATABASE]");
var request = {
    database : formattedDatabase
};
// Write request objects.
stream.write(request);

matchAnyPathFromAnyPathName

matchAnyPathFromAnyPathName(anyPathName) returns String

Parses the anyPathName from a any_path resource.

Parameter

anyPathName

String

A fully-qualified path representing a any_path resources.

Returns

String 

  • A string representing the any_path.

matchDatabaseFromAnyPathName

matchDatabaseFromAnyPathName(anyPathName) returns String

Parses the anyPathName from a any_path resource.

Parameter

anyPathName

String

A fully-qualified path representing a any_path resources.

Returns

String 

  • A string representing the database.

matchDatabaseFromDatabaseRootName

matchDatabaseFromDatabaseRootName(databaseRootName) returns String

Parses the databaseRootName from a database_root resource.

Parameter

databaseRootName

String

A fully-qualified path representing a database_root resources.

Returns

String 

  • A string representing the database.

matchDatabaseFromDocumentPathName

matchDatabaseFromDocumentPathName(documentPathName) returns String

Parses the documentPathName from a document_path resource.

Parameter

documentPathName

String

A fully-qualified path representing a document_path resources.

Returns

String 

  • A string representing the database.

matchDatabaseFromDocumentRootName

matchDatabaseFromDocumentRootName(documentRootName) returns String

Parses the documentRootName from a document_root resource.

Parameter

documentRootName

String

A fully-qualified path representing a document_root resources.

Returns

String 

  • A string representing the database.

matchDocumentFromAnyPathName

matchDocumentFromAnyPathName(anyPathName) returns String

Parses the anyPathName from a any_path resource.

Parameter

anyPathName

String

A fully-qualified path representing a any_path resources.

Returns

String 

  • A string representing the document.

matchDocumentPathFromDocumentPathName

matchDocumentPathFromDocumentPathName(documentPathName) returns String

Parses the documentPathName from a document_path resource.

Parameter

documentPathName

String

A fully-qualified path representing a document_path resources.

Returns

String 

  • A string representing the document_path.

matchProjectFromAnyPathName

matchProjectFromAnyPathName(anyPathName) returns String

Parses the anyPathName from a any_path resource.

Parameter

anyPathName

String

A fully-qualified path representing a any_path resources.

Returns

String 

  • A string representing the project.

matchProjectFromDatabaseRootName

matchProjectFromDatabaseRootName(databaseRootName) returns String

Parses the databaseRootName from a database_root resource.

Parameter

databaseRootName

String

A fully-qualified path representing a database_root resources.

Returns

String 

  • A string representing the project.

matchProjectFromDocumentPathName

matchProjectFromDocumentPathName(documentPathName) returns String

Parses the documentPathName from a document_path resource.

Parameter

documentPathName

String

A fully-qualified path representing a document_path resources.

Returns

String 

  • A string representing the project.

matchProjectFromDocumentRootName

matchProjectFromDocumentRootName(documentRootName) returns String

Parses the documentRootName from a document_root resource.

Parameter

documentRootName

String

A fully-qualified path representing a document_root resources.

Returns

String 

  • A string representing the project.

rollback

rollback(request, options, callback) returns Promise

Rolls back a transaction.

Parameter

request

Object

The request object that will be sent.

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 formattedDatabase = client.databaseRootPath("[PROJECT]", "[DATABASE]");
var transaction = '';
var request = {
    database: formattedDatabase,
    transaction: transaction
};
client.rollback(request).catch(function(err) {
    console.error(err);
});

runQuery

runQuery(request, options) returns Stream

Runs a query.

Parameter

request

Object

The request object that will be sent.

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 RunQueryResponse on 'data' event.

Example

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

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

var formattedParent = client.anyPathPath("[PROJECT]", "[DATABASE]", "[DOCUMENT]", "[ANY_PATH]");
client.runQuery({parent: formattedParent}).on('data', function(response) {
  // doThingsWith(response)
});

updateDocument

updateDocument(request, options, callback) returns Promise

Updates or inserts a document.

Parameter

request

Object

The request object that will be sent.

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 document = {};
var updateMask = {};
var request = {
    document: document,
    updateMask: updateMask
};
client.updateDocument(request).then(function(responses) {
    var response = responses[0];
    // doThingsWith(response)
})
.catch(function(err) {
    console.error(err);
});

write

write(options) returns Stream

Streams batches of document updates and deletes, in order.

Parameter

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 is both readable and writable. It accepts objects representing WriteRequest for write() method, and will emit objects representing WriteResponse on 'data' event asynchronously.

Example

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

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

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