Class DocumentReference (7.7.0)

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]CollectionReference to a subcollection.

DocumentReference

Package

@google-cloud/firestore

Remarks

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the DocumentReference class.

Properties

firestore

get firestore(): Firestore;

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

{Firestore} DocumentReference#firestore

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

get id(): string;

The last path element of the referenced document.

{string} DocumentReference#id

Example


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

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

parent

get parent(): CollectionReference<AppModelType, DbModelType>;

A reference to the collection to which this DocumentReference belongs.

DocumentReference#parent {CollectionReference}

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

get path(): string;

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

{string} DocumentReference#path

Example


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

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

Methods

collection(collectionPath)

collection(collectionPath: string): CollectionReference;

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

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

Returns
Type	Description
`CollectionReference`	{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)

create(data: firestore.WithFieldValue<AppModelType>): Promise<WriteResult>;

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

Parameter
Name	Description
`data`	`FirebaseFirestore.WithFieldValue<AppModelType>` An object that contains the fields and data to serialize as the document.

Returns

Type Description

Promise<WriteResult>

{Promise.

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(precondition)

delete(precondition?: firestore.Precondition): 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).

Parameter
Name	Description
`precondition`	`firestore.Precondition` A precondition to enforce for this delete.

Returns

Type Description

Promise<WriteResult>

{Promise.

Example


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

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

get()

get(): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

Reads the document referred to by this DocumentReference.

Returns

Type Description

Promise<DocumentSnapshot<AppModelType, DbModelType>>

{Promise.

Example


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

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

isEqual(other)

isEqual(other: firestore.DocumentReference<AppModelType, DbModelType>): boolean;

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

Parameter
Name	Description
`other`	`FirebaseFirestore.DocumentReference<AppModelType, DbModelType>` The value to compare against. {boolean} true if this `DocumentReference` is equal to the provided value.

Returns
Type	Description
`boolean`

listCollections()

listCollections(): Promise<Array<CollectionReference>>;

Fetches the subcollections that are direct children of this document.

Returns

Type Description

Promise<Array<CollectionReference>>

{Promise.<Array.

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, onError)

onSnapshot(onNext: (snapshot: firestore.DocumentSnapshot<AppModelType, DbModelType>) => void, onError?: (error: Error) => void): () => void;

Attaches a listener for DocumentSnapshot events.

Parameters
Name	Description
`onNext`	`(snapshot: FirebaseFirestore.DocumentSnapshot<AppModelType, DbModelType>) => void` A callback to be called every time a new `DocumentSnapshot` is available.
`onError`	`(error: Error) => void` 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
`() => void`	{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, options)

set(data: firestore.PartialWithFieldValue<AppModelType>, options: firestore.SetOptions): Promise<WriteResult>;

Parameters
Name	Description
`data`	`FirebaseFirestore.PartialWithFieldValue<AppModelType>`
`options`	`firestore.SetOptions`

Returns
Type	Description
`Promise<WriteResult>`

set(data)

set(data: firestore.WithFieldValue<AppModelType>): Promise<WriteResult>;

Parameter
Name	Description
`data`	`FirebaseFirestore.WithFieldValue<AppModelType>`

Returns
Type	Description
`Promise<WriteResult>`

update(dataOrField, preconditionOrValues)

update(dataOrField: firestore.UpdateData<DbModelType> | string | firestore.FieldPath, ...preconditionOrValues: Array<unknown | string | firestore.FieldPath | firestore.Precondition>): 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	Description
`dataOrField`	`FirebaseFirestore.UpdateData<DbModelType> \| string \| FirebaseFirestore.FieldPath` An object containing the fields and values with which to update the document or the path of the first field to update.
`preconditionOrValues`	`Array<unknown \| string \| FirebaseFirestore.FieldPath \| FirebaseFirestore.Precondition>` An alternating list of field paths and values to update or a Precondition to restrict this update.

Returns

Type Description

Promise<WriteResult>

{Promise.

Example


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

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

withConverter(converter)

withConverter(converter: null): DocumentReference;

Parameter
Name	Description
`converter`	`null`

Returns
Type	Description
`DocumentReference`

withConverter(converter)

withConverter<NewAppModelType, NewDbModelType extends firestore.DocumentData = firestore.DocumentData>(converter: firestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;

Parameter
Name	Description
`converter`	`FirebaseFirestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>`

Returns
Type	Description
`DocumentReference<NewAppModelType, NewDbModelType>`

Type Parameters
Name	Description
`NewAppModelType`
`NewDbModelType`