document.update()

Learn: Documents

Update a collection document's fields.

Signature

update(data: { ttl: Time | Null, data: Null, *: Any }) => <Document>

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.

Remove a field

To remove a document field, set its value in the data object to null.

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

Object

true

Object with the updated document fields.

The object can’t include the following metadata fields:

  • id

  • coll

  • ts

  • data

Return value

Type Description

<Document>

The updated collection document.

A document’s data type is taken from its collection’s name. For example, Product for a document in the Product collection. See Document type.

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")
}
\