> 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: insert(collectionId: string, item: object, options: WixDataOptions)

# Method package: wixData

# Method menu location: wixData --> insert

# Method Link: https://dev.wix.com/docs/velo/apis/wix-data/insert.md

# Method Description:

Adds an item to a collection.

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()`](wix-data.Hooks.html#beforeInsert)
 and [`afterInsert()`](wix-data.Hooks.html#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 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()`
 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 to `null` 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 the [`update()`](#update) and [`save()`](#save) functions.
> - The `insert()` function does not support multi-reference fields. For multi-reference fields, use [`insertReference()`](https://www.wix.com/velo/reference/wix-data/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()` will fail and issue an error.



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## Insert an item into a collection

```javascript
import wixData from 'wix-data';

// ...

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.insert("myCollection", toInsert)
  .then((item) => {
console.log(item); //see item below
    })
  .catch((err) => {
    console.log(err);
  });

/*  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 wixData from 'wix-data';

// ...

let toInsert = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.insert("myCollection", toInsert)
  .then((results) => {
    let item = results; //see item below
  })
  .catch((err) => {
    let errorMsg = err;
  });

/*  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 into a collection using data options

```javascript
import wixData from 'wix-data';

// ...

let toInsert = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.insert("myCollection", toInsert, options)
  .then((item) => {
    console.log(item); //see item below
  })
  .catch((err) => {
  console.log(err);
  });

/*  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 wixData from 'wix-data';

// ...

let countryId = "id-of-usa-item";

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryId
};

wixData.insert("myCollection", toInsert)
  .then((results) => {
    console.log(item); //see item below
  })
  .catch((err) => {
    console.log(err);
  });

/*  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 wixData from 'wix-data';

// ...

let countryItem = // get country item from somewhere

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryItem
};

wixData.insert("myCollection", toInsert)
  .then((results) => {
    console.log(item); //see item below
})
  .catch((err) => {
    console.log(err);
});

/*  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 wixData from 'wix-data';

// Code for a create operation using insert() //

function createGreeting(language, greeting) {
  const toInsert = {
    language,
    greeting
  };

  return wixData.insert('Greetings', toInsert);
}

```

---