document.update()
| Learn: Documents |
|---|
Update a collection document's fields.
Description
Updates a collection document with fields from a provided data object.
During the update, fields from the data object are copied to the document, creating new fields or updating existing fields. The operation is similar to a merge.
Metadata fields
You can’t use this method to insert or edit the following metadata fields:
-
id -
coll -
ts -
data
Nested fields
Fields with nested objects in the data object are merged with the identically named nested object in the document.
Default values
A field definition can set a
default field value for
documents in a collection. Default values are not inserted for missing or null
fields during a document update.
Reserved fields
You can’t use this method to insert or edit the following metadata fields:
-
id -
coll -
ts -
data
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
data |
true |
Object with the updated document fields. The object can’t include the following metadata fields:
|
Return value
| Type | Description |
|---|---|
<Document> |
The updated collection document. A document’s data type is taken from its collection’s name. For example,
|
Examples
Given the following document:
{
id: "777",
coll: Product,
ts: Time("2099-04-10T16:50:12.850Z"),
name: "limes",
description: "Conventional, 16 oz bag",
price: 2_99,
stock: 30,
category: Category("789")
}Call update() with an object containing updated document fields:
Product.byId("777")?.update({
name: "key limes",
stock: 100
}){
id: "777",
coll: Product,
ts: Time("2099-04-10T16:50:12.850Z"),
name: "key limes",
description: "Conventional, 16 oz bag",
price: 299,
stock: 100,
category: Category("789")
}Remove a field
To remove a document field, set its value to null. Fields with null values
aren’t stored or returned.
Product.byId("777")?.update({
stock: null
}){
id: "777",
coll: Product,
ts: Time("2099-04-10T17:59:50.970Z"),
name: "limes",
description: "Conventional, 16 oz bag",
price: 299,
category: Category("789")
}