(cache)DocumentReference

new DocumentReference()

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.

Members

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

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

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

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(collectionPath) → {CollectionReference}

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

Parameters:

Name	Type	Description
`collectionPath`	string	A slash-separated path to a collection.

Returns:

Type	Description
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(data) → {Promise.<WriteResult>}

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

Parameters:

Name	Type	Description
`data`	DocumentData	An object that contains the fields and data to serialize as the document.

Returns:

Type	Description
Promise.<WriteResult>	A Promise that resolves with the write time of this create.

Throws:

If the provided input is not a valid Firestore document or if the document already exists.
Type Error

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(preconditionopt) → {Promise.<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).

Parameters:

Name Type Attributes Description

precondition

Precondition

A precondition to enforce for this delete.

Properties

Name	Type	Attributes	Description
`lastUpdateTime`	Timestamp	<optional>	If set, enforces that the document was last updated at lastUpdateTime. Fails the delete if the document was last updated at a different time.
`exists`	boolean	<optional>	If set, enforces that the target document must or must not exist.

Returns:

Type	Description
Promise.<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() → {Promise.<DocumentSnapshot>}

Reads the document referred to by this DocumentReference.

Returns:

Type	Description
Promise.<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.');
  }
});
```

isEqual(other) → {boolean}

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

Parameters:

Name	Type	Description
`other`	*	The value to compare against.

Returns:

Type	Description
boolean	true if this `DocumentReference` is equal to the provided value.

listCollections() → {Promise.<Array.<CollectionReference>>}

Fetches the subcollections that are direct children of this document.

Returns:

Type	Description
Promise.<Array.<CollectionReference>>	A Promise that resolves with an array of CollectionReferences.

Example

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

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

onSnapshot(onNext, onErroropt) → {function}

Attaches a listener for DocumentSnapshot events.

Parameters:

Name	Type	Attributes	Description
`onNext`	documentSnapshotCallback		A callback to be called every time a new `DocumentSnapshot` is available.
`onError`	errorCallback	<optional>	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:

Type	Description
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(data, optionsopt) → {Promise.<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.

Parameters:

Name Type Attributes Description

data

T | Partial.<AppModelType>

A map of the fields and values for the document.

options

SetOptions

An object to configure the set behavior.

Properties

Name	Type	Attributes	Description
`merge`	boolean	<optional>	If true, set() merges the values specified in its data argument. Fields omitted from this set() call remain untouched. If your input sets any field to an empty map, all nested fields are overwritten.
`mergeFields`	Array.<(string\|FieldPath)>	<optional>	If provided, set() only replaces the specified field paths. Any field path that is not specified is ignored and remains untouched. If your input sets any field to an empty map, all nested fields are overwritten.

Returns:

Type	Description
Promise.<WriteResult>	A Promise that resolves with the write time of this set.

Throws:

If the provided input is not a valid Firestore document.
Type Error

Example

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

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

update(dataOrField, …preconditionOrValues) → {Promise.<WriteResult>}

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.

Parameters:

Name	Type	Attributes	Description
`dataOrField`	UpdateData \| string \| FieldPath		An object containing the fields and values with which to update the document or the path of the first field to update.
`preconditionOrValues`	* \| string \| FieldPath \| Precondition	<repeatable>	An alternating list of field paths and values to update or a Precondition to restrict this update.

Returns:

Type	Description
Promise.<WriteResult>	A Promise that resolves once the data has been successfully written to the backend.

Throws:

If the provided input is not valid Firestore data.
Type Error

Example

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

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

withConverter(converter)

Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call set(), get(), etc. on the returned DocumentReference instance, the provided converter will convert between Firestore data of type NewDbModelType and your custom type NewAppModelType.

Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore.

Passing in null as the converter parameter removes the current converter.

Parameters:

Name	Type	Description
`converter`	FirestoreDataConverter \| null	Converts objects to and from Firestore. Passing in `null` removes the current converter.

Returns:

Type	Description
	A DocumentReference that uses the provided converter.

Example

```
class Post {
  constructor(readonly title: string, readonly author: string) {}

  toString(): string {
    return this.title + ', by ' + this.author;
  }
}

const postConverter = {
  toFirestore(post: Post): FirebaseFirestore.DocumentData {
    return {title: post.title, author: post.author};
  },
  fromFirestore(
    snapshot: FirebaseFirestore.QueryDocumentSnapshot
  ): Post {
    const data = snapshot.data();
    return new Post(data.title, data.author);
  }
};

const postSnap = await Firestore()
  .collection('posts')
  .withConverter(postConverter)
  .doc().get();
const post = postSnap.data();
if (post !== undefined) {
  post.title; // string
  post.toString(); // Should be defined
  post.someNonExistentProperty; // TS error
}

```