v1.FirestoreClient

Parameters

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.

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

Return a fully-qualified any_path resource name string.

Returns

String 

batchGetDocuments(request[, options]) → Stream

Gets multiple documents.

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

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

Returns

Stream 

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

beginTransaction(request[, options][, callback]) → Promise

Starts a new transaction.

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

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.

commit(request[, options][, callback]) → Promise

Commits a transaction, while optionally updating documents.

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

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.

createDocument(request[, options][, callback]) → Promise

Creates a new document.

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

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.

databaseRootPath(project, database) → String

Return a fully-qualified database_root resource name string.

Returns

String 

deleteDocument(request[, options][, callback]) → Promise

Deletes a document.

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

Returns

Promise 

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

documentPathPath(project, database, documentPath) → String

Return a fully-qualified document_path resource name string.

Returns

String 

documentRootPath(project, database) → String

Return a fully-qualified document_root resource name string.

Returns

String 

getDocument(request[, options][, callback]) → Promise

Gets a single document.

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

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.

getProjectId(callback)

Return the project ID used by this class.

listCollectionIds(request[, options][, callback]) → Promise

Lists all the collection IDs underneath a document.

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 (const resource of resources) {
      // doThingsWith(resource)
    }
  })
  .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 (const resource of resources) {
    // doThingsWith(resource);
  }
  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);
  });

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.

listCollectionIdsStream(request[, options]) → 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.

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

See also

https://nodejs.org/api/stream.html

Returns

Stream 

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

listDocuments(request[, options][, callback]) → Promise

Lists documents.

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 (const resource of resources) {
      // doThingsWith(resource)
    }
  })
  .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 (const resource of resources) {
    // doThingsWith(resource);
  }
  if (nextRequest) {
    // Fetch the next page.
    return client.listDocuments(nextRequest, options).then(callback);
  }
}
client.listDocuments(request, options)
  .then(callback)
  .catch(err => {
    console.error(err);
  });

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.

listDocumentsStream(request[, options]) → 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.

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

See also

https://nodejs.org/api/stream.html

Returns

Stream 

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

listen([options]) → Stream

Listens to changes.

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

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.

matchAnyPathFromAnyPathName(anyPathName) → String

Parse the anyPathName from a any_path resource.

Returns

String 

• A string representing the any_path.

matchDatabaseFromAnyPathName(anyPathName) → String

Parse the anyPathName from a any_path resource.

Returns

String 

• A string representing the database.

matchDatabaseFromDatabaseRootName(databaseRootName) → String

Parse the databaseRootName from a database_root resource.

Returns

String 

• A string representing the database.

matchDatabaseFromDocumentPathName(documentPathName) → String

Parse the documentPathName from a document_path resource.

Returns

String 

• A string representing the database.

matchDatabaseFromDocumentRootName(documentRootName) → String

Parse the documentRootName from a document_root resource.

Returns

String 

• A string representing the database.

matchDocumentFromAnyPathName(anyPathName) → String

Parse the anyPathName from a any_path resource.

Returns

String 

• A string representing the document.

matchDocumentPathFromDocumentPathName(documentPathName) → String

Parse the documentPathName from a document_path resource.

Returns

String 

• A string representing the document_path.

matchProjectFromAnyPathName(anyPathName) → String

Parse the anyPathName from a any_path resource.

Returns

String 

• A string representing the project.

matchProjectFromDatabaseRootName(databaseRootName) → String

Parse the databaseRootName from a database_root resource.

Returns

String 

• A string representing the project.

matchProjectFromDocumentPathName(documentPathName) → String

Parse the documentPathName from a document_path resource.

Returns

String 

• A string representing the project.

matchProjectFromDocumentRootName(documentRootName) → String

Parse the documentRootName from a document_root resource.

Returns

String 

• A string representing the project.

rollback(request[, options][, callback]) → Promise

Rolls back a transaction.

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

Returns

Promise 

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

runQuery(request[, options]) → Stream

Runs a query.

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

Returns

Stream 

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

updateDocument(request[, options][, callback]) → Promise

Updates or inserts a document.

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

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.

write([options]) → Stream

Streams batches of document updates and deletes, in order.

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

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.