v1. 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 greaterread_time
is guaranteed to see the effects of the transaction.
Constructor
FirestoreClient
new FirestoreClient(options)
Construct an instance of FirestoreClient.
Parameter |
|||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Optional object The configuration object. See the subsequent parameters for more details. Values in
|
Properties
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
anyPathPath
anyPathPath(project, database, document, anyPath) returns String
Return 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
|
||||||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); const documents = []; const request = { database:
formattedDatabase, documents: documents,
};
client.batchGetDocuments(request).on('data', 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
|
||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); client.beginTransaction({database: formattedDatabase})
.then(responses => {
const response = responses[0];
// doThingsWith(response)
})
.catch(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
|
||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); const writes = []; const request = { database:
formattedDatabase, writes: writes,
};
client.commit(request)
.then(responses => {
const response = responses[0];
// doThingsWith(response)
})
.catch(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
|
||||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); const collectionId = ''; const documentId =
''; const document = {}; const request = { parent: formattedParent,
collectionId: collectionId,
documentId: documentId,
document: document,
};
client.createDocument(request)
.then(responses => {
const response = responses[0];
// doThingsWith(response)
})
.catch(err => {
console.error(err);
});
databaseRootPath
databaseRootPath(project, database) returns String
Return 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
|
||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); client.deleteDocument({name:
formattedName}).catch(err => { console.error(err);
});
documentPathPath
documentPathPath(project, database, documentPath) returns String
Return a fully-qualified document_path resource name string.
Parameter |
|
---|---|
project |
String |
database |
String |
documentPath |
String |
- Returns
-
String
documentRootPath
documentRootPath(project, database) returns String
Return 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. Values in
|
||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); client.getDocument({name: formattedName})
.then(responses => {
const response = responses[0];
// doThingsWith(response)
})
.catch(err => {
console.error(err);
});
getProjectId
getProjectId(callback)
Return 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. Values in
|
||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
// Iterate over all elements.
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]');
client.listCollectionIds({parent: formattedParent})
.then(responses => {
const resources = responses[0];
for (let i = 0; i < resources.length; i += 1) {
// doThingsWith(resources[i])
}
})
.catch(err => {
console.error(err);
});
// Or obtain the paged response.
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]');
const options = {autoPaginate: false};
const callback = responses => {
// The actual resources in a response.
const resources = responses[0];
// The next request if the response shows that there are more responses.
const nextRequest = responses[1];
// The actual response object, if necessary.
// const rawResponse = responses[2];
for (let i = 0; i < resources.length; i += 1) {
// doThingsWith(resources[i]);
}
if (nextRequest) {
// Fetch the next page.
return client.listCollectionIds(nextRequest, options).then(callback);
}
}
client.listCollectionIds({parent: formattedParent}, options)
.then(callback)
.catch(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. Values in
|
||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); client.listCollectionIdsStream({parent:
formattedParent}) .on('data', element => {
// doThingsWith(element)
}).on('error', err => {
console.log(err);
});
listDocuments
listDocuments(request, options, callback) returns Promise
Lists documents.
Parameter |
|||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object The request object that will be sent. Values in
|
||||||||||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
// Iterate over all elements.
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); const collectionId = ''; const request = {
parent: formattedParent,
collectionId: collectionId,
};
client.listDocuments(request)
.then(responses => {
const resources = responses[0];
for (let i = 0; i < resources.length; i += 1) {
// doThingsWith(resources[i])
}
})
.catch(err => {
console.error(err);
});
// Or obtain the paged response.
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); const collectionId = ''; const request = {
parent: formattedParent,
collectionId: collectionId,
};
const options = {autoPaginate: false};
const callback = responses => {
// The actual resources in a response.
const resources = responses[0];
// The next request if the response shows that there are more responses.
const nextRequest = responses[1];
// The actual response object, if necessary.
// const rawResponse = responses[2];
for (let i = 0; i < resources.length; i += 1) {
// doThingsWith(resources[i]);
}
if (nextRequest) {
// Fetch the next page.
return client.listDocuments(nextRequest, options).then(callback);
}
}
client.listDocuments(request, options)
.then(callback)
.catch(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. Values in
|
||||||||||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); const collectionId = ''; const request = {
parent: formattedParent,
collectionId: collectionId,
};
client.listDocumentsStream(request)
.on('data', element => {
// doThingsWith(element)
}).on('error', 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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const stream = client.listen().on('data', response => {
// doThingsWith(response)
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); const request = { database: formattedDatabase,
};
// Write request objects.
stream.write(request);
matchAnyPathFromAnyPathName
matchAnyPathFromAnyPathName(anyPathName) returns String
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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
Parse 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. Values in
|
||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); const transaction = ''; const request = { database:
formattedDatabase, transaction: transaction,
};
client.rollback(request).catch(err => {
console.error(err);
});
runQuery
runQuery(request, options) returns Stream
Runs a query.
Parameter |
|||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object The request object that will be sent. Values in
|
||||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]',
'[DOCUMENT]', '[ANY_PATH]'); client.runQuery({parent:
formattedParent}).on('data', 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. Values in
|
||||||||||
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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const document = {};
const updateMask = {};
const request = {
document: document,
updateMask: updateMask,
};
client.updateDocument(request)
.then(responses => {
const response = responses[0];
// doThingsWith(response)
})
.catch(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
const firestore = require('@google-cloud/firestore');
const client = new firestore.v1.FirestoreClient({
// optional auth parameters.
});
const stream = client.write().on('data', response => {
// doThingsWith(response)
});
const formattedDatabase = client.databaseRootPath('[PROJECT]',
'[DATABASE]'); const request = { database: formattedDatabase,
};
// Write request objects.
stream.write(request);