> 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 # Method name: data.items.insert(dataCollectionId: string, item: Partial, options: WixDataInsertOptions) # Method Link: https://dev.wix.com/docs/sdk/business-solutions/data/items/insert.md # Method Description: Adds an item to a collection. An item can only be inserted into an existing collection. You can create a new collection using the Data Collections API. The `insert()` method 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()` method triggers the [`beforeInsert()`](https://dev.wix.com/docs/velo/api-reference/wix-data/hooks/before-insert.md) and [`afterInsert()`](https://dev.wix.com/docs/velo/api-reference/wix-data/hooks/after-insert.md) hooks if they have been defined. 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()` method 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()` method 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. > **Notes:** > - The maximum size of an item that you can add to a collection is 500kb. > - 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](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection), an item with the system field `_id` is pre-inserted into the collection. [Single-item collections](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection) may contain only one item. > - If there is a pre-existing item in a [single-item collection](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection), the `insert()` method will not run. To update or change an item in a single-item collection see the `update()` and `save()` methods. > - The `insert()` method does not support multi-reference fields. For multi-reference fields, use `insertReference()`. > - [Translatable collections](https://support.wix.com/en/article/wix-multilingual-translating-cms-collection-content) 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()` fails and issues an error. # Method Permissions: - Write Data Items # Method Permissions Scopes IDs: - SCOPE.DC-DATA.WRITE # Method Code Examples: ## Insert an item into a collection ```javascript import { items } from "@wix/data"; async function insertItem() { const toInsert = { "title": "Mr.", "first_name": "John", "last_name": "Doe" }; const inserted = await items.insert("myCollection", toInsert); console.log(inserted); // See below } /* item is: * * { * "_id": "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */ ``` ## Insert an item with a specified ID into a collection ```javascript import { items } from "@wix/data"; async function insertItem() { const toInsert = { "_id": "00001", "title": "Mr.", "first_name": "John", "last_name": "Doe" }; const inserted = await items.insert("myCollection", toInsert); console.log(inserted); } /* item is: * * { * "_id": "00001", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */ ``` ## Insert an item including a reference to another item using the referenced item's ID ```javascript import { items } from "@wix/data"; async function insertItem() { const countryId = "id-of-usa-item"; const toInsert = { "title": "Mr.", "first_name": "John", "last_name": "Doe", "country": countryId }; const inserted = await items.insert("myCollection", toInsert); console.log(inserted); // See below } /* item is: * * { * "_id": "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe", * "country": "id-of-usa-item" * } */ ``` ## Insert an item including a reference to another item using the reference item ```javascript import { items } from "@wix/data"; async function insertItem() { const countryItem = // Get country item const toInsert = { "title": "Mr.", "first_name": "John", "last_name": "Doe", "country": countryItem }; const inserted = await items.insert("myCollection", toInsert); console.log(inserted); // See below } /* item is: * * { * "_id": "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe", * "country": "id-of-usa-item" * } */ ``` ## Insert an item into a collection using a custom function ```javascript import { items } from "@wix/data"; // Create an operation using insert() // function createGreeting(language, greeting) { const toInsert = { language, greeting }; return items.insert('Greetings', toInsert); } ``` ## default ```javascript try { const result = await items.insert("collection-0.28758841360566656", { _id: "1ad20d72-f217-4663-b1c1-47fe7b9fcde5", name: "Sample Item", phone: "+972501234567", image: "https://static.wixstatic.com/media/503ea4_ed9a38760ae04aab86b47e82525fdcac~mv2.jpg", createdDate: Date.now(), updatedDate: Date.now() }, { suppressHooks: false }); return result; } catch (error) { console.error(error); throw error; } ```