Class DocumentReference (6.0.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<T> 
 );

Constructs a new instance of the DocumentReference class

Parameters

Name	Description
_firestore	`Firestore` The Firestore Database client.
_path	`ResourcePath` The Path of this reference.
_converter	`FirebaseFirestore.FirestoreDataConverter <T>` The converter to use when serializing data.

Properties

_converter

  readonly 
  
 _converter 
 : 
  
 firestore 
 . 
 FirestoreDataConverter<T> 
 ;

_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<T> 
 ;

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<T> 
 ) 
 : 
  
 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 <T>` 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<T> 
> ;

Reads the document referred to by this DocumentReference.

Returns

Type	Description
Promise < DocumentSnapshot <T>>	{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<T> 
 ) 
 : 
  
 boolean 
 ;

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

Parameter

Name	Description
other	`FirebaseFirestore.DocumentReference <T>` 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<firestore 
 . 
 DocumentData 
>>> ;

Fetches the subcollections that are direct children of this document.

Returns

Type	Description
Promise < Array < CollectionReference < FirebaseFirestore.DocumentData >>>	{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<T> 
 ) 
  
 = 
>  
 void 
 , 
  
 onError 
 ?: 
  
 ( 
 error 
 : 
  
 Error 
 ) 
  
 = 
>  
 void 
 ) 
 : 
  
 () 
  
 = 
>  
 void 
 ;

Attaches a listener for DocumentSnapshot events.

Parameters

Name	Description
onNext	`(snapshot: FirebaseFirestore.DocumentSnapshot <T>) => 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<T> 
 , 
  
 options 
 : 
  
 firestore 
 . 
 SetOptions 
 ) 
 : 
  
 Promise<WriteResult> 
 ;

Parameters

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

Returns

Type	Description
Promise < WriteResult >

set(data)

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

Parameter

Name	Description
data	`FirebaseFirestore.WithFieldValue <T>`

Returns

Type	Description
Promise < WriteResult >

update(dataOrField, preconditionOrValues)

  update 
 ( 
 dataOrField 
 : 
  
 firestore 
 . 
 UpdateData<T> 
  
 | 
  
 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 <T> \| 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<firestore 
 . 
 DocumentData 
> ;

Parameter

Name	Description
converter	`null`

Returns

Type	Description
DocumentReference < FirebaseFirestore.DocumentData >

withConverter(converter)

  withConverter<U> 
 ( 
 converter 
 : 
  
 firestore 
 . 
 FirestoreDataConverter<U> 
 ) 
 : 
  
 DocumentReference<U> 
 ;

Parameter

Name	Description
converter	`FirebaseFirestore.FirestoreDataConverter <U>`

Returns

Type	Description
DocumentReference <U>

Type Parameter

Name	Description
U

Class DocumentReference (6.0.0) Stay organized with collections Save and categorize content based on your preferences.

Package

Constructors

(constructor)(_firestore, _path, _converter)

Properties

_converter

_path

firestore

id

parent

path

Methods

collection(collectionPath)

create(data)

delete(precondition)

get()

isEqual(other)

listCollections()

onSnapshot(onNext, onError)

set(data, options)

set(data)

update(dataOrField, preconditionOrValues)

withConverter(converter)

withConverter(converter)

Class DocumentReference (6.0.0)