insert( )

Adds an item to a collection.

Description

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 the item with collection, if the item does not include one. 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 200kb.

Syntax

function insert(collectionId: string, item: Object, [options: WixDataOptions]): Promise<Object>

insert Parameters

NAME

TYPE

DESCRIPTION

collectionId

string

The ID of the collection to add the item to.

item

Object

The item to add.

options

Optional

WixDataOptions

An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Returns

Fulfilled - The item that was added. Rejected - The error that caused the rejection.

Return Type:

Promise<Object>

Was this helpful?

Insert an item into a collection

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert = {
6  "title":        "Mr.",
7  "first_name":   "John",
8  "last_name":    "Doe"
9};
10
11wixData.insert("myCollection", toInsert)
12	.then( (results) => {
13		let item = results; //see item below
14	} )
15	.catch( (err) => {
16		let errorMsg = err;
17	} );
18
19/*  item is:
20 *
21 *  {
22 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
23 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
24 *    "_createdDate": "2017-05-24T12:33:18.938Z",
25 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
26 *    "title":        "Mr.",
27 *    "first_name":   "John",
28 *    "last_name":    "Doe"
29 *  }
30 */

Insert an item with a specified ID into a collection

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert = {
6  "_id":          "00001",
7  "title":        "Mr.",
8  "first_name":   "John",
9  "last_name":    "Doe"
10};
11
12wixData.insert("myCollection", toInsert)
13	.then( (results) => {
14		let item = results; //see item below
15	} )
16	.catch( (err) => {
17		let errorMsg = err;
18	} );
19
20/*  item is:
21 *
22 *  {
23 *    "_id":          "00001",
24 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
25 *    "_createdDate": "2017-05-24T12:33:18.938Z",
26 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
27 *    "title":        "Mr.",
28 *    "first_name":   "John",
29 *    "last_name":    "Doe"
30 *  }
31 */

Insert an item into a collection using data options

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert = {
6  "_id":          "00001",
7  "title":        "Mr.",
8  "first_name":   "John",
9  "last_name":    "Doe"
10};
11
12let options = {
13  "suppressAuth": true,
14  "suppressHooks": true
15};
16
17wixData.insert("myCollection", toInsert, options)
18	.then( (results) => {
19		let item = results; //see item below
20	} )
21	.catch( (err) => {
22		let errorMsg = err;
23	} );
24
25/*  item is:
26 *
27 *  {
28 *    "_id":          "00001",
29 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
30 *    "_createdDate": "2017-05-24T12:33:18.938Z",
31 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
32 *    "title":        "Mr.",
33 *    "first_name":   "John",
34 *    "last_name":    "Doe"
35 *  }
36 */

Insert an item including a reference to another item using the referenced item's ID

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let countryId = "id-of-usa-item";
6
7let toInsert = {
8  "title":        "Mr.",
9  "first_name":   "John",
10  "last_name":    "Doe",
11  "country":      countryId
12};
13
14wixData.insert("myCollection", toInsert)
15  .then( (results) => {
16    let item = results; //see item below
17  } )
18  .catch( (err) => {
19    let errorMsg = err;
20  } );
21
22/*  item is:
23 *
24 *  {
25 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
26 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
27 *    "_createdDate": "2017-05-24T12:33:18.938Z",
28 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
29 *    "title":        "Mr.",
30 *    "first_name":   "John",
31 *    "last_name":    "Doe",
32 *    "country":      "id-of-usa-item"
33 *  }
34 */

Insert an item including a reference to another item using the reference item

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let countryItem = // get country item from somewhere
6
7let toInsert = {
8  "title":        "Mr.",
9  "first_name":   "John",
10  "last_name":    "Doe",
11  "country":      countryItem
12};
13
14wixData.insert("myCollection", toInsert)
15  .then( (results) => {
16    let item = results; //see item below
17  } )
18  .catch( (err) => {
19    let errorMsg = err;
20  } );
21
22/*  item is:
23 *
24 *  {
25 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
26 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
27 *    "_createdDate": "2017-05-24T12:33:18.938Z",
28 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
29 *    "title":        "Mr.",
30 *    "first_name":   "John",
31 *    "last_name":    "Doe",
32 *    "country":      "id-of-usa-item"
33 *  }
34 */