Class: DocumentReference<T>
Holds a reference to a document. A document reference is a reference to a specific record in a collection. You can use it to read or write data to the document. A document can refer to a row in a table in a relational database or a document in a NoSQL database. Additionally, a document reference can refer to a non-existent document, which you can use to create a new document.
Read more about document references in the documentation.
Type parameters
| Name | Type | Description |
|---|---|---|
T | extends DocumentData = any | The type of the document data. |
Properties
refId
• refId: string
A string that uniquely identifies this document reference.
Accessors
data
• get data(): T
Returns the document data. Throws an error if the document does not exist.
Returns
T
The document data.
Throws
Error if the document does not exist.
dataRef
• get dataRef(): T
Returns a read-only internal copy of the document data. This works similar to this.data, except it does not
perform a defensive copy. The caller may not modify this object, on penalty of unexpected behavior.
Returns
T
The document data.
Throws
Error if the document does not exist.
hasData
• get hasData(): boolean
Returns whether data has been populated for this document reference. Data will not present if a document has not been queried, does not exist, or has been deleted.
Returns
boolean
Whether the document has data.
Methods
decrementInPath
▸ decrementInPath(path, value, transactionId?): Promise<void>
Decrements the value at the given path by the given value. The value may be both positive and negative.
Parameters
| Name | Type | Description |
|---|---|---|
path | Paths<T> | The path to the value to decrement. |
value | number | The value to decrement by. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
delete
▸ delete(transactionId?): Promise<void>
Deletes the document.
The delete will be reflected optimistically locally and will be applied to the server later.
If a transactionId is provided, the delete will be applied to the server as an atomic operation together with
the rest of the operations in the transaction and the delete will not reflect locally until the transaction is
completed locally.
The returned promise will resolve once the delete has been applied to the server or immediately if the delete
is part of a transaction.
Parameters
| Name | Type | Description |
|---|---|---|
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
deleteInPath
▸ deleteInPath(path, transactionId?): Promise<void>
Similar to update, but only deletes the given path.
Parameters
| Name | Type | Description |
|---|---|---|
path | Paths<T> | The path to delete. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
incrementInPath
▸ incrementInPath(path, value, transactionId?): Promise<void>
Increments the value at the given path by the given value. The value may be both positive and negative.
Parameters
| Name | Type | Description |
|---|---|---|
path | Paths<T> | The path to the value to increment. |
value | number | The value to increment by. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
insert
▸ insert(data, transactionId?): Promise<void>
Inserts the document with the given data. If the document already exists, the operation will be treated as
upsert. The insert will be reflected optimistically locally and will be applied to the server later. If a
transactionId is provided, the insert will be applied to the server as an atomic operation together with the
rest
of the operations in the transaction and the insert will not reflect locally until the transaction is completed
locally.
The returned promise will resolve once the insert has been applied to the server or immediately if the insert
is part of a transaction.
Parameters
| Name | Type | Description |
|---|---|---|
data | Omit<T, "__id"> | The data to insert. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
isDirty
▸ isDirty(): boolean
Returns whether the locally available version of the document may not be the latest version on the server.
Returns
boolean
Whether the locally available version of the document may not be the latest version on the server.
peek
▸ peek(): undefined | T
Returns the data that is currently available on the client or undefined if data has not yet been populated.
Returns
undefined | T
The data that is currently available on the client or undefined if data has not yet been populated.
setInPath
▸ setInPath<K>(path, value, transactionId?): Promise<void>
Similar to update, but only updates the given path.
Type parameters
| Name |
|---|
K |
Parameters
| Name | Type | Description |
|---|---|---|
path | K | The path to update. |
value | { [k in string | number | symbol]-?: k extends string | number ? Record<`${k}`, T[k]> | (Required<T>[k] extends any[] ? never : Required<T>[k] extends object ? ({ [k in keyof Required<T>[k]]-?: k extends string | number ? Record<`${k}.${k}`, Required<T>[k][k]> | (Required<Required<T>[k]>[k] extends any[] ? never : Required<...>[k] extends object ? { [k in keyof Required<...>[k]]-?: k extends string | number ? Record<...> | (Required<...>[k] extends any[] ? never : Required<...)[keyof any[any]] : never) : never }[keyof T][`K`] | The value to set at the given path. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>
snapshot
▸ snapshot(): Promise<undefined | T>
A promise that resolves with the latest data from the server or undefined if the document does not exist on the server.
Returns
Promise<undefined | T>
A promise that resolves with latest data from the server or undefined if the document does not exist on the server.
snapshots
▸ snapshots(): Observable<undefined | T>
Returns an observable that emits the latest data from the server or undefined if the document is deleted or does not exist on the server.
Returns
Observable<undefined | T>
An observable that emits the latest data from the server or undefined if the document is deleted or does not exist on the server.
update
▸ update(data, transactionId?): Promise<void>
Updates the document with the given data.
The update will be reflected optimistically locally and will be applied to the server later.
If a transactionId is provided, the update will be applied to the server as an atomic operation together with
the rest of the operations in the transaction and the update will not reflect locally until the transaction is
completed locally.
The returned promise will resolve once the update has been applied to the server or immediately if the update
is part of a transaction.
Parameters
| Name | Type | Description |
|---|---|---|
data | Partial<{ [k in string | number | symbol]-?: k extends string | number ? Record<`${k}`, T[k]> | (Required<T>[k] extends any[] ? never : Required<T>[k] extends object ? ({ [k in keyof Required<T>[k]]-?: k extends string | number ? Record<`${k}.${k}`, Required<T>[k][k]> | (Required<Required<T>[k]>[k] extends any[] ? never : Required<...>[k] extends object ? { [k in keyof Required<...>[k]]-?: k extends string | number ? Record<...> | (Required<...>[k] extends any[] ? never : Required<...)[keyof any[any]] : never) : never }[keyof T]> | The data to update - can be partial. |
transactionId? | string | The transaction to use for this operation. If not provided, the operation will be applied immediately. |
Returns
Promise<void>