insert( )

Adds an item to a collection.

The insert() function returns a Promise that resolves to the inserted item after it has been added to the specified collection. The Promise is rejected if the current user does not have "create" permissions for the collection or the specified item includes an _id property whose value matches an existing ID in the collection. Meaning, insert() cannot overwrite an existing item in the collection.

Calling the insert() function triggers the beforeInsert() and afterInsert() hooks if they have been defined.

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

When inserting an item into 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 insert() function adds the following properties and values to the item when it adds it to the collection:

  • _id: A unique identifier for an item in a collection, if the item doesn't have one or has one that is undefined. You can optionally provide your own ID. Once an ID is assigned to an item it cannot be changed.
  • _createdDate: The date the item was added to the collection.
  • _updatedDate: The date the item was modified. When the item is first added, the _createdDate and _updatedDate are the same.

Any valid JavaScript object can be added as a property value. The insert() function maintains the structure of the specified object. For example, objects that contain nested objects, Arrays, or Arrays with nested objects are all added to the collection as defined.

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

Notes:

  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • When creating a Single Item Collection, an item with the system field _id is pre-inserted into the collection. Single Item Collections may contain only one item.
  • If there is a pre-existing item in a Single Item Collection, the insert() function will not run. To update or change an item in a Single Item Collection see the update() and save() functions.
  • The insert() function does not support multi-reference fields. For multi-reference fields, use insertReference().
  • 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 insert() will fail and issue an error.
Method Declaration
Copy
Method Parameters
collectionIdstringRequired

The ID of the collection to add 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.

itemItemRequired

The item to add.

optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
Did this help?