Search...

APIs

bulkInsert( )

Adds a number of items to a collection.

Description

The bulkInsert() function returns a Promise that resolves after the items have been added to the specified collection. The Promise is rejected if the current user does not have create permissions for the collection. Items are skipped if they include an _id property whose value matches an existing ID in the collection. Meaning, bulkInsert() cannot overwrite an existing item in the collection.

Calling the bulkInsert() function triggers the beforeInsert() and afterInsert() hooks for each item that is inserted if the hooks have been defined.

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

When inserting items into a collection that has a reference field, set the values of the reference fields to the referenced item's _id value or the entire referenced item object.

The bulkInsert() 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 bulkInsert() 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.

Note: Bulk operations are limited to 1000 items per function call.

Syntax

function bulkInsert(collectionId: string, items: Array<Object>, [options: WixDataOptions]): Promise<WixDataBulkResult>

bulkInsert Parameters

NAME

TYPE

DESCRIPTION

collectionId

string

The ID of the collection to add the item to.

items

Array<Object>

The items to add.

options

Optional

WixDataOptions

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

Returns

Fulfilled - The results of the bulk insert. Rejected - The error that caused the rejection.

Return Type:

Promise<WixDataBulkResult>

NAME

TYPE

DESCRIPTION

inserted

number

The number of inserted items.

updated

number

The number of updated items.

skipped

number

The number of skipped items.

insertedItemIds

Array<string>

List of IDs of inserted items.

errors

Array<Error>

List of errors.

removed

number

The number of removed items.

removedItemIds

Array<string>

List of IDs of removed items.

Was this helpful?

Insert multiple items into a collection

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert1 = {
6  "title":        "Mr.",
7  "first_name":   "John",
8  "last_name":    "Doe"
9};
10
11let toInsert2 = {
12  "title":        "Ms.",
13  "first_name":   "Jane",
14  "last_name":    "Doe"
15};
16
17wixData.bulkInsert("myCollection", [toInsert1, toInsert2])
18  .then( (results) => {
19    let inserted = results.inserted; // 2
20    let insertedIds = results.insertedItemIds; // see below
21    let updated = results.updated; // 0
22    let skipped = results.skipped; // 0
23    let errors = results.errors; // []
24  } )
25  .catch( (err) => {
26    let errorMsg = err;
27  } );
28
29/*  insertedIds is:
30 *
31 *  [
32 *    "d9ea65a6-726a-4c3e-b97d-1128c0a06b5f",
33 *    "472c1da9-e5e4-4620-8ee3-962e9d1a7df5"
34 *  ]
35 */

Insert multiple items with specified IDs into a collection

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert1 = {
6  "_id":          "00001",
7  "title":        "Mr.",
8  "first_name":   "John",
9  "last_name":    "Doe"
10};
11
12let toInsert2 = {
13  "_id":          "00002",
14  "title":        "Ms.",
15  "first_name":   "Jane",
16  "last_name":    "Doe"
17};
18
19wixData.bulkInsert("myCollection", [toInsert1, toInsert2])
20  .then( (results) => {
21    let inserted = results.inserted; // 2
22    let insertedIds = results.insertedItemIds; // ["00001", "00002"]
23    let updated = results.updated; // 0
24    let skipped = results.skipped; // 0
25    let errors = results.errors; // []
26  } )
27  .catch( (err) => {
28    let errorMsg = err;
29  } );

Insert multiple items into a collection using data options

Code Example

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let toInsert1 = {
6  "_id":          "00001",
7  "title":        "Mr.",
8  "first_name":   "John",
9  "last_name":    "Doe"
10};
11
12let toInsert2 = {
13  "_id":          "00002",
14  "title":        "Ms.",
15  "first_name":   "Jane",
16  "last_name":    "Doe"
17};
18
19let options = {
20  "suppressAuth": true,
21  "suppressHooks": true
22};
23
24wixData.bulkInsert("myCollection", [toInsert1, toInsert2], options)
25  .then( (results) => {
26    let inserted = results.inserted; // 2
27    let insertedIds = results.insertedItemIds; // ["00001", "00002"]
28    let updated = results.updated; // 0
29    let skipped = results.skipped; // 0
30    let errors = results.errors; // []
31  } )
32  .catch( (err) => {
33    let errorMsg = err;
34  } );

Insert multiple items 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 toInsert1 = {
8  "title":        "Mr.",
9  "first_name":   "John",
10  "last_name":    "Doe",
11  "country":      countryId
12};
13
14let toInsert2 = {
15  "title":        "Ms.",
16  "first_name":   "Jane",
17  "last_name":    "Doe",
18  "country":      countryId
19};
20
21wixData.bulkInsert("myCollection", [toInsert1, toInsert2])
22  .then( (results) => {
23    let inserted = results.inserted; // 2
24    let insertedIds = results.insertedItemIds; // see below
25    let updated = results.updated; // 0
26    let skipped = results.skipped; // 0
27    let errors = results.errors; // []
28  } )
29  .catch( (err) => {
30    let errorMsg = err;
31  } );
32
33/*  insertedIds is:
34 *
35 *  [
36 *    "d9ea65a6-726a-4c3e-b97d-1128c0a06b5f",
37 *    "472c1da9-e5e4-4620-8ee3-962e9d1a7df5"
38 *  ]
39 */

Insert multiple items 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 toInsert1 = {
8  "title":        "Mr.",
9  "first_name":   "John",
10  "last_name":    "Doe",
11  "country":      countryItem
12};
13
14let toInsert2 = {
15  "title":        "Ms.",
16  "first_name":   "Jane",
17  "last_name":    "Doe",
18  "country":      countryItem
19};
20
21wixData.bulkInsert("myCollection", [toInsert1, toInsert2])
22  .then( (results) => {
23    let inserted = results.inserted; // 2
24    let insertedIds = results.insertedItemIds; // see below
25    let updated = results.updated; // 0
26    let skipped = results.skipped; // 0
27    let errors = results.errors; // []
28  } )
29  .catch( (err) => {
30    let errorMsg = err;
31  } );
32
33/*  insertedIds is:
34 *
35 *  [
36 *    "d9ea65a6-726a-4c3e-b97d-1128c0a06b5f",
37 *    "472c1da9-e5e4-4620-8ee3-962e9d1a7df5"
38 *  ]
39 */