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 an item in a collection, if the item doesn't have one or has one that isundefined
. 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 tonull
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 theupdate()
andsave()
functions.
Authorization
Request
This endpoint does not take any parameters
Response Object
Fulfilled - The item that was added. Rejected - The error that caused the rejection.
Returns an empty object.
Status/Error Codes
Was this helpful?
1import wixData from 'wix-data';23// ...45let toInsert = {6 "title": "Mr.",7 "first_name": "John",8 "last_name": "Doe"9};1011wixData.insert("myCollection", toInsert)12 .then((item) => {13console.log(item); //see item below14 })15 .catch((err) => {16 console.log(err);17 });1819/* 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 */
1import wixData from 'wix-data';23// ...45let toInsert = {6 "_id": "00001",7 "title": "Mr.",8 "first_name": "John",9 "last_name": "Doe"10};1112wixData.insert("myCollection", toInsert)13 .then((results) => {14 let item = results; //see item below15 })16 .catch((err) => {17 let errorMsg = err;18 });1920/* 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 */
1import wixData from 'wix-data';23// ...45let toInsert = {6 "_id": "00001",7 "title": "Mr.",8 "first_name": "John",9 "last_name": "Doe"10};1112let options = {13 "suppressAuth": true,14 "suppressHooks": true15};1617wixData.insert("myCollection", toInsert, options)18 .then((item) => {19 console.log(item); //see item below20 })21 .catch((err) => {22 console.log(err);23 });2425/* 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 */
1import wixData from 'wix-data';23// ...45let countryId = "id-of-usa-item";67let toInsert = {8 "title": "Mr.",9 "first_name": "John",10 "last_name": "Doe",11 "country": countryId12};1314wixData.insert("myCollection", toInsert)15 .then((results) => {16 console.log(item); //see item below17 })18 .catch((err) => {19 console.log(err);20 });2122/* 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 */
1import wixData from 'wix-data';23// ...45let countryItem = // get country item from somewhere67let toInsert = {8 "title": "Mr.",9 "first_name": "John",10 "last_name": "Doe",11 "country": countryItem12};1314wixData.insert("myCollection", toInsert)15 .then((results) => {16 console.log(item); //see item below17})18 .catch((err) => {19 console.log(err);20});2122/* 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 */
In this example, we demonstrate how you can you can build a CRUD "create" function using insert()
. You can test out the code in our example template.
1import wixData from 'wix-data';23// Code for a create operation using insert() //45function createGreeting(language, greeting) {6 const toInsert = {7 language,8 greeting9 };1011 return wixData.insert('Greetings', toInsert);12}13