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/firestoreConstructors
(constructor)(_firestore, _path, _converter)
constructor
(
_firestore
:
Firestore
,
_path
:
ResourcePath
,
_converter
?:
firestore
.
FirestoreDataConverter<AppModelType
,
DbModelType
> );
Constructs a new instance of the DocumentReference
class
_firestore
_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
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
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}
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
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.
collectionPath
string
A slash-separated path to a collection.
{CollectionReference} A reference to the new subcollection.
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.
data
FirebaseFirestore.WithFieldValue
<AppModelType>
An object that contains the fields and data to serialize as the document.
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).
precondition
firestore.Precondition
A precondition to enforce for this delete.
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.
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.
other
FirebaseFirestore.DocumentReference
<AppModelType, DbModelType>
The value to compare against. {boolean} true if this DocumentReference
is equal to the provided value.
boolean
listCollections()
listCollections
()
:
Promise<Array<CollectionReference>
> ;
Fetches the subcollections that are direct children of this document.
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.
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.
() => void
{function()} An unsubscribe function that can be called to cancel the snapshot listener.
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>
;
data
FirebaseFirestore.PartialWithFieldValue
<AppModelType>
options
firestore.SetOptions
set(data)
set
(
data
:
firestore
.
WithFieldValue<AppModelType>
)
:
Promise<WriteResult>
;
data
FirebaseFirestore.WithFieldValue
<AppModelType>
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.
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.
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
;
converter
null
withConverter(converter)
withConverter<NewAppModelType
,
NewDbModelType
extends
firestore
.
DocumentData
=
firestore
.
DocumentData
> (
converter
:
firestore
.
FirestoreDataConverter<NewAppModelType
,
NewDbModelType
> )
:
DocumentReference<NewAppModelType
,
NewDbModelType
> ;
converter
FirebaseFirestore.FirestoreDataConverter
<NewAppModelType, NewDbModelType>
NewAppModelType
NewDbModelType
