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
| Name | Description |
| _firestore |
Firestore
The Firestore Database client. |
| _path |
ResourcePath
The Path of this reference. |
| _converter |
FirebaseFirestore.FirestoreDataConverter<T>
|
Properties
_converter
readonly _converter: firestore.FirestoreDataConverter<T>;| Type | Description |
| FirebaseFirestore.FirestoreDataConverter<T> |
_path
readonly _path: ResourcePath;| Type | Description |
| ResourcePath |
_resourcePath
get _resourcePath(): ResourcePath;Returns a resource path for this document.
| Type | Description |
| ResourcePath |
firestore
get firestore(): Firestore;The [Firestore]Firestore instance for the Firestore database (useful for performing transactions, etc.).
{Firestore} DocumentReference#firestore
| Type | Description |
| Firestore |
formattedName
get formattedName(): string;The string representation of the DocumentReference's location. {string} DocumentReference#formattedName
| Type | Description |
| string |
id
get id(): string;The last path element of the referenced document.
{string} DocumentReference#id
| Type | Description |
| string |
parent
get parent(): CollectionReference<T>;A reference to the collection to which this DocumentReference belongs.
DocumentReference#parent {CollectionReference}
| Type | Description |
| CollectionReference<T> |
path
get path(): string;A string representing the path of the referenced document (relative to the root of the database).
{string} DocumentReference#path
| Type | Description |
| string |
Methods
collection(collectionPath)
collection(collectionPath: string): CollectionReference;Gets a [CollectionReference]CollectionReference instance that refers to the collection at the specified path.
| Name | Description |
| collectionPath |
string
A slash-separated path to a collection. |
| Type | Description |
| CollectionReference | {CollectionReference} A reference to the new subcollection. |
create(data)
create(data: T): Promise<WriteResult>;Create a document with the provided object values. This will fail the write if a document exists at its location.
| Name | Description |
| data |
T
An object that contains the fields and data to serialize as the document. |
| Type | Description |
| Promise<WriteResult> | {Promise.
|
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).
| Name | Description |
| precondition |
firestore.Precondition
A precondition to enforce for this delete. |
| Type | Description |
| Promise<WriteResult> | {Promise.
|
get()
get(): Promise<DocumentSnapshot<T>>;Reads the document referred to by this DocumentReference.
| Type | Description |
| Promise<DocumentSnapshot<T>> | {Promise.
|
isEqual(other)
isEqual(other: firestore.DocumentReference<T>): boolean;Returns true if this DocumentReference is equal to the provided value.
| Name | Description |
| other |
FirebaseFirestore.DocumentReference<T>
The value to compare against. {boolean} true if this |
| Type | Description |
| boolean |
listCollections()
listCollections(): Promise<Array<CollectionReference<firestore.DocumentData>>>;Fetches the subcollections that are direct children of this document.
| Type | Description |
| Promise<Array<CollectionReference<FirebaseFirestore.DocumentData>>> | {Promise.<Array.
|
onSnapshot(onNext, onError)
onSnapshot(onNext: (snapshot: firestore.DocumentSnapshot<T>) => void, onError?: (error: Error) => void): () => void;Attaches a listener for DocumentSnapshot events.
| Name | Description |
| onNext |
(snapshot: FirebaseFirestore.DocumentSnapshot<T>) => void
A callback to be called every time a new |
| 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. |
| Type | Description |
| () => void | {function()} An unsubscribe function that can be called to cancel the snapshot listener. |
set(data, options)
set(data: Partial<T>, options: firestore.SetOptions): Promise<WriteResult>;| Name | Description |
| data |
Partial<T>
|
| options |
firestore.SetOptions
|
| Type | Description |
| Promise<WriteResult> |
set(data)
set(data: T): Promise<WriteResult>;| Name | Description |
| data |
T
|
| Type | Description |
| Promise<WriteResult> |
toProto()
toProto(): api.IValue;Converts this DocumentReference to the Firestore Proto representation.
| Type | Description |
| api.IValue |
update(dataOrField, preconditionOrValues)
update(dataOrField: firestore.UpdateData | 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.
| Name | Description |
| dataOrField |
FirebaseFirestore.UpdateData | 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. |
| Type | Description |
| Promise<WriteResult> | {Promise.
|
withConverter(converter)
withConverter(converter: null): DocumentReference<firestore.DocumentData>;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 and your custom type U.
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.
| Name | Description |
| converter |
null
Converts objects to and from Firestore. Passing in
|
| Type | Description |
| DocumentReference<FirebaseFirestore.DocumentData> |
withConverter(converter)
withConverter<U>(converter: firestore.FirestoreDataConverter<U>): DocumentReference<U>;| Name | Description |
| converter |
FirebaseFirestore.FirestoreDataConverter<U>
|
| Type | Description |
| DocumentReference<U> |
| Name | Description |
| U |