Class DocumentReference (7.1.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

Constructors

(constructor)(_firestore, _path, _converter)

constructor(_firestore: Firestore, 
    _path: ResourcePath, 
    _converter?: firestore.FirestoreDataConverter<AppModelType, DbModelType>);

Constructs a new instance of the DocumentReference class

Parameters
NameDescription
_firestore Firestore

The Firestore Database client.

_path ResourcePath

The Path of this reference.

_converter FirebaseFirestore.FirestoreDataConverter<AppModelType, DbModelType>

The converter to use when serializing data.

Properties

_converter

readonly _converter: firestore.FirestoreDataConverter<AppModelType, DbModelType>;

_path

readonly _path: ResourcePath;

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
NameDescription
collectionPath string

A slash-separated path to a collection.

Returns
TypeDescription
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
NameDescription
data FirebaseFirestore.WithFieldValue<AppModelType>

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

Returns
TypeDescription
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
NameDescription
precondition firestore.Precondition

A precondition to enforce for this delete.

Returns
TypeDescription
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
TypeDescription
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
NameDescription
other FirebaseFirestore.DocumentReference<AppModelType, DbModelType>

The value to compare against. {boolean} true if this DocumentReference is equal to the provided value.

Returns
TypeDescription
boolean

listCollections()

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

Fetches the subcollections that are direct children of this document.

Returns
TypeDescription
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
NameDescription
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
TypeDescription
() => 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
NameDescription
data FirebaseFirestore.PartialWithFieldValue<AppModelType>
options firestore.SetOptions
Returns
TypeDescription
Promise<WriteResult>

set(data)

set(data: firestore.WithFieldValue<AppModelType>): Promise<WriteResult>;
Parameter
NameDescription
data FirebaseFirestore.WithFieldValue<AppModelType>
Returns
TypeDescription
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
NameDescription
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
TypeDescription
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
NameDescription
converter null
Returns
TypeDescription
DocumentReference

withConverter(converter)

withConverter<NewAppModelType, NewDbModelType extends firestore.DocumentData = firestore.DocumentData>(converter: firestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
Parameter
NameDescription
converter FirebaseFirestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>
Returns
TypeDescription
DocumentReference<NewAppModelType, NewDbModelType>
Type Parameters
NameDescription
NewAppModelType
NewDbModelType