> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# BulkInsertDataItems

# Package: cms

# Namespace: DataItemService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-items.md

## Permission Scopes:
Write Data Items: SCOPE.DC-DATA.WRITE

## Introduction

Adds multiple items to a collection.


To add a single item, call Insert Data Item instead.

When each item is inserted into a collection, its ID is automatically assigned a random value.
You can optionally provide your own ID when inserting the item. If you specify an ID that already exists in the collection, the insertion will fail.

---

## REST API

### Schema

```
 Method: bulkInsertDataItems
 Description: Adds multiple items to a collection.   To add a single item, call Insert Data Item instead.  When each item is inserted into a collection, its GUID is automatically assigned a random value. You can optionally provide your own GUID when inserting the item. If you specify an GUID that already exists in the collection, the insertion will fail.
 URL: https://www.wixapis.com/wix-data/v2/bulk/items/insert
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, dataItems
 Method parameters: 
   param name: appOptions | type: appOptions | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying.  When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. 
   param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection in which to insert the items. | required: true
   param name: dataItems | type: array<dataItems> | description: Data items to insert. | required: true
              - name: id | type: string | description: Data item GUID. 
              - name: data | type: object | description: Data item contents.  Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:  + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. 
   param name: returnEntity | type: returnEntity | description: Whether to return the inserted data items. When `true`, the `results` objects contain a `dataItem` field.  Default: `false` 
 Return type: BulkInsertDataItemsResponse
  - name: results | type: array<BulkDataItemResult> | description: Information about the inserted items. 
     - name: action | type: BulkActionType | description: Action attempted for the data item. 
         - enum: UNKNOWN_ACTION_TYPE, INSERT, UPDATE, DELETE, PATCH
     - name: itemMetadata | type: ItemMetadata | description: Item metadata. 
        - name: id | type: string | description: Item GUID. Does not appear if the item GUID is missing. For example, when item creation fails. 
        - name: originalIndex | type: integer | description: Original index of the item in the array specified in the request. Use this to match items in the request with those in the response. 
        - name: success | type: boolean | description: Whether the requested action was successful. When `false`, the `error` field is populated. 
        - name: error | type: ApplicationError | description: In case of failure, the error details. 
           - name: code | type: string | description: Error code. 
           - name: description | type: string | description: Description of the error. 
           - name: data | type: object | description: Data related to the error. 
     - name: dataItem | type: DataItem | description: Updated data item.  Returned if `returnEntity` is set to `true` and the action is successful. 
        - name: id | type: string | description: Data item GUID. 
        - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to 
        - name: data | type: object | description: Data item contents.  Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:  + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. 
  - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata. 
     - name: totalSuccesses | type: integer | description: Number of items successfully processed. 
     - name: totalFailures | type: integer | description: Number of items that couldn't be processed. 


```

### Examples

### Bulk insert new items
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "dataItems": [
        {
            "data": {
                "state": "California",
                "year": 2022,
                "city": "Los Angeles",
                "population": 3800000
            }
        },
        {
            "data": {
                "state": "California",
                "year": 2022,
                "city": "San Francisco",
                "population": 840000
            }
        }
    ]
}'
```

### Bulk insert new items and return inserted items
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "dataItems": [
        {
            "data": {
                "state": "California",
                "year": 2022,
                "city": "Los Angeles",
                "population": 3800000
            }
        },
        {
            "data": {
                "state": "California",
                "year": 2022,
                "city": "San Francisco",
                "population": 840000
            }
        }
    ],
    "returnEntity": true
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.cms.DataItemService.bulkInsertDataItems(dataCollectionId, items, options)
 Description: Adds multiple items to a collection.   To add a single item, call Insert Data Item instead.  When each item is inserted into a collection, its GUID is automatically assigned a random value. You can optionally provide your own GUID when inserting the item. If you specify an GUID that already exists in the collection, the insertion will fail.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, items
 Method parameters: 
   param name: dataCollectionId | type: string | description: GUID of the collection in which to insert the items. | required: true
   param name: items | type: array<array> | description: Data items to insert. | required: true
              - name: _id | type: string | description: Data item GUID. 
              - name: _createdDate | type: Date | description: Date and time the item was added to the collection. 
              - name: _updatedDate | type: Date | description: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. 
              - name: _owner | type: string | description: GUID of the user who created the item. Can be modified with site owner permissions. 
   param name: options | type: WixDataBulkInsertOptions  none 
        - name: dataItems | type: array<DataItem> | description: Data items to insert. 
           - name: _id | type: string | description: Data item GUID. 
           - name: data | type: object | description: Data item contents.  Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields:  + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. 
        - name: suppressHooks | type: boolean | description: Whether to suppress data hooks. When `true`, data hooks typically triggered by this endpoint don't run.  **Note:** This option can only be used in code that runs in [the Wix site backend](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/about-the-site-backend.md).  Default: `false` 
        - name: appOptions | type: object | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying.  When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. 
        - name: saveReferences | type: boolean | description: Whether to create references from multi-reference fields. When `true`, array values in multi-reference fields are extracted and stored as references linking each inserted item to its referenced items. Multi-reference field values must be arrays of referenced item GUIDs (strings) or referenced items containing an `_id` field.  Default: `false` 
        - name: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. Default: `false`. 
 Return type: PROMISE<WixDataBulkResult>
  - name: inserted | type: integer | description: Number of inserted items. 
  - name: updated | type: integer | description: Number of updated items. 
  - name: removed | type: integer | description: Number of removed items. 
  - name: skipped | type: integer | description: Number of skipped items. 
  - name: errors | type: array<WixDataBulkError> | description: List of errors. 
     - name: message | type: string | description: Description of the error. 
     - name: code | type: string | description: Error code. 
     - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items. 
     - name: item | type: string | description: Failed item (or GUID in case of `bulkRemove()`). 
  - name: insertedItemIds | type: array | description: List of GUIDs of inserted items. 
  - name: updatedItemIds | type: array | description: List of GUIDs of updated items. 
  - name: removedItemIds | type: array | description: List of GUIDs of removed items. 


```

### Examples

### bulkInsert
```javascript
import { items } from '@wix/data';

async function bulkInsert(dataCollectionId,items,options) {
  const response = await items.bulkInsert(dataCollectionId,items,options);
};
```

### bulkInsert (with elevated permissions)
```javascript
import { items } from '@wix/data';
import { auth } from '@wix/essentials';

async function myBulkInsertMethod(dataCollectionId,items,options) {
  const elevatedBulkInsert = auth.elevate(items.bulkInsert);
  const response = await elevatedBulkInsert(dataCollectionId,items,options);
}
```

### bulkInsert (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { items } from '@wix/data';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { items },
  // Include the auth strategy and host as relevant
});


async function bulkInsert(dataCollectionId,items,options) {
  const response = await myWixClient.items.bulkInsert(dataCollectionId,items,options);
};
```

---