save( )

Inserts or updates an item in a collection.

The save() function returns a Promise that resolves to the inserted or updated item after it has been added or updated in the specified collection. The Promise is rejected if the current user does not have the necessary permissions for the collection.

The save() function inserts or updates the specified item, depending on whether it already exists in the collection. It compares the _id property value of the specified item with the _id property values of the items in the specified collection. If an item in the collection has that _id value, save() uses update() to update the item in the collection, triggering the beforeUpdate() and afterUpdate() hooks if they have been defined. If none of the items in the collection contain that _id value, the specified item does not have an _id property, or if the specified item's id property is undefined, save() uses insert() to add the specified item to the collection. This triggers the beforeInsert() and afterInsert() hooks if they have been defined.

Use the options parameter to run save() from backend code without checking for permissions or without its registered hooks.

When saving an item to a collection that has a reference field, set the value of the reference field to the referenced item's _id value or the entire referenced item object.

The maximum size of an item that you can save to a collection is 500kb.


  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • The save() function does not support multi-reference fields. For multi-reference fields, use insertReference() or replaceReferences()
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling save() will fail and issue an error.
Method Declaration
Method Parameters

The ID of the collection to save the item to.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


The item to insert or update.


An object containing options to use when processing this operation.

Return Type:Promise<object>
Was this helpful?