@google-cloud/firestore 0.15.4 » Class: DocumentReference

DocumentReference

class

A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. A DocumentReference can also be used to create a CollectionReference to a subcollection.

Properties

firestore

read-only

Firestore

The Firestore instance for the Firestore database (useful for performing transactions, etc.).

Example

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  let firestore = documentReference.firestore;
  console.log(`Root location for document is ${firestore.formattedName}`);
});

id

read-only

string

The last path element of the referenced document.

Example

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  console.log(`Added document with name '${documentReference.id}'`);
});

parent

read-only

CollectionReference

A reference to the collection to which this DocumentReference belongs.

Example

let documentRef = firestore.doc('col/doc');
let collectionRef = documentRef.parent;

collectionRef.where('foo', '==', 'bar').get().then(results => {
  console.log(`Found ${results.size} matches in parent collection`);
}):

path

read-only

string

A string representing the path of the referenced document (relative to the root of the database).

Example

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  console.log(`Added document at '${documentReference.path}'`);
});

Methods

collection

collection(collectionPath) returns CollectionReference

Gets a CollectionReference instance that refers to the collection at the specified path.

Parameter
collectionPath	string A slash-separated path to a collection.

Returns

CollectionReference 

A reference to the new subcollection.

Example

let documentRef = firestore.doc('col/doc');
let subcollection = documentRef.collection('subcollection');
console.log(`Path to subcollection: ${subcollection.path}`);

create

create(data) returns Promise containing WriteResult

Create a document with the provided object values. This will fail the write if a document exists at its location.

Parameter
data	DocumentData An object that contains the fields and data to serialize as the document.

Returns

Promise containing WriteResult 

A Promise that resolves with the write time of this create.

Example

let documentRef = firestore.collection('col').doc();

documentRef.create({foo: 'bar'}).then((res) => {
  console.log(`Document created at ${res.updateTime}`);
}).catch((err) => {
  console.log(`Failed to create document: ${err}`);
});

delete

delete(precondition) returns Promise containing WriteResult

Deletes the document referred to by this DocumentReference.

A delete for a non-existing document is treated as a success (unless lastUptimeTime is provided).

Parameter
precondition	Optional Precondition A precondition to enforce for this delete. Values in precondition have the following properties: Parameter lastUpdateTime Optional Timestamp If set, enforces that the document was last updated at lastUpdateTime. Fails the delete if the document was last updated at a different time.

Returns

Promise containing WriteResult 

A Promise that resolves with the delete time.

Example

let documentRef = firestore.doc('col/doc');

documentRef.delete().then(() => {
  console.log('Document successfully deleted.');
});

get

get() returns Promise containing DocumentSnapshot

Retrieve a document from the database. Fails the Promise if the document is not found.

Returns

Promise containing DocumentSnapshot 

A Promise resolved with a DocumentSnapshot for the retrieved document on success. For missing documents, DocumentSnapshot.exists will be false. If the get() fails for other reasons, the Promise will be rejected.

Example

let documentRef = firestore.doc('col/doc');

documentRef.get().then(documentSnapshot => {
  if (documentSnapshot.exists) {
    console.log('Document retrieved successfully.');
  }
});

getCollections

getCollections() returns Promise containing Array of CollectionReference

Fetches the subcollections that are direct children of this document.

Returns

Promise containing Array of CollectionReference 

A Promise that resolves with an array of CollectionReferences.

Example

let documentRef = firestore.doc('col/doc');

documentRef.getCollections().then(collections => {
  for (let collection of collections) {
    console.log(`Found subcollection with id: ${collection.id}`);
  }
});

isEqual

isEqual(other) returns boolean

Returns true if this DocumentReference is equal to the provided value.

Parameter
other	any type The value to compare against.

Returns

boolean 

true if this DocumentReference is equal to the provided value.

onSnapshot

onSnapshot(onNext, onError) returns function()

Attaches a listener for DocumentSnapshot events.

Parameter
onNext	documentSnapshotCallback A callback to be called every time a new DocumentSnapshot is available.
onError	Optional errorCallback A callback to be called if the listen fails or is cancelled. No further callbacks will occur. If unset, errors will be logged to the console.

Returns

function() 

An unsubscribe function that can be called to cancel the snapshot listener.

Example

let documentRef = firestore.doc('col/doc');

let unsubscribe = documentRef.onSnapshot(documentSnapshot => {
  if (documentSnapshot.exists) {
    console.log(documentSnapshot.data());
  }
}, err => {
  console.log(`Encountered error: ${err}`);
});

// Remove this listener.
unsubscribe();

set

set(data, options) returns Promise containing WriteResult

Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.

Parameter
data	DocumentData A map of the fields and values for the document.
options	Optional SetOptions An object to configure the set behavior. Values in options have the following properties: Parameter merge Optional boolean If true, set() merges the values specified in its data argument. Fields omitted from this set() call remain untouched. mergeFields Optional Array of (string or FieldPath) If provided, set() only replaces the specified field paths. Any field path that is not specified is ignored and remains untouched.

Returns

Promise containing WriteResult 

A Promise that resolves with the write time of this set.

Example

let documentRef = firestore.doc('col/doc');

documentRef.set({foo: 'bar'}).then(res => {
  console.log(`Document written at ${res.updateTime}`);
});

update

update(dataOrField, ...preconditionOrValues)

Updates fields in the document referred to by this DocumentReference. If the document doesn't yet exist, the update fails and the returned Promise will be rejected.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values.

A Precondition restricting this update can be specified as the last argument.

Parameter
dataOrField	(UpdateData, string, or FieldPath) An object containing the fields and values with which to update the document or the path of the first field to update.
preconditionOrValues	(any type, string, FieldPath, or Precondition) An alternating list of field paths and values to update or a Precondition to restrict this update. Value may be repeated.

Returns

Promise. A Promise that resolves once the data has been successfully written to the backend.

Example

let documentRef = firestore.doc('col/doc');

documentRef.update({foo: 'bar'}).then(res => {
  console.log(`Document updated at ${res.updateTime}`);
});