<commit_before>---
code: true
type: page
title: create
---

# create

<SinceBadge version="1.0.0" />

Creates a new [collection](/core/2/guides/essentials/store-access-data), in the provided `index`.

Collection names must meet the following criteria:

* Lowercase only
* Cannot include one of the following characters: `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), `,`, `#`, `:`, `%`, `&`, `.`
* Cannot be longer than 126 bytes (note it is bytes, so multi-byte characters will count towards the 126 limit faster)

You can also provide an optional body with a [collection mapping](/core/2/guides/essentials/database-mappings) allowing you to exploit the full capabilities of our persistent data storage layer.

This method will only update the mapping when the collection already exists.

You can define the collection [dynamic mapping policy](/core/2/guides/essentials/database-mappings#dynamic-mapping-policy) by setting the `dynamic` field to the desired value.

You can define [collection additional metadata](/core/2/guides/essentials/database-mappings#collection-metadata) within the `_meta` root field.

<SinceBadge version="2.1.0">

You can also provide Elasticsearch index [settings]((https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings)) when creating a new collection.

---

## Query Syntax

### HTTP

```http
URL: http://kuzzle:7512/<index>/<collection>
Method: PUT
Body:
```

<SinceBadge version="2.1.0">

```js
{
  "mappings": {
    "dynamic": "[true|false|strict]",
    "_meta": {
      "field": "value"
    },
    "properties": {
      "field1": {
        "type": "integer"
      },
      "field2": {
        "type": "keyword"
      },
      "field3": {
        "type":   "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  },
  "settings": {
    "analysis" : {
      "analyzer":{
        "content":{
          "type":"custom",
          "tokenizer":"whitespace"
        }
      }
    }
  }
}
```

<DeprecatedBadge version="2.1.0">

```js
{
  "dynamic": "[false|true|strict]",
  "_meta": {
    "field": "value"
  },
  "properties": {
    "field1": {
      "type": "integer"
    },
    "field2": {
      "type": "keyword"
    },
    "field3": {
      "type":   "date",
      "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
    }
  }
}
```

### Other protocols

<SinceBadge version="2.1.0">

```js
{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "body": {
    "mappings": {
      "dynamic": "[true|false|strict]",
      "_meta": {
        "field": "value"
      },
      "properties": {
        "field1": {
          "type": "integer"
        },
        "field2": {
          "type": "keyword"
        },
        "field3": {
          "type":   "date",
          "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
        }
      }
    },
    "settings": {
      "analysis" : {
        "analyzer":{
          "content":{
            "type":"custom",
            "tokenizer":"whitespace"
          }
        }
      }
    }
  }
}
```

<DeprecatedBadge version="2.1.0">

```js
{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "body": {
    "dynamic": "[true|false|strict]",
    "_meta": {
      "field": "value"
    },
    "properties": {
      "field1": {
        "type": "integer"
      },
      "field2": {
        "type": "keyword"
      },
      "field3": {
        "type":   "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  }
}
```


---

## Arguments

- `collection`: name of the collection to create
- `index`: index name

---

## Body properties

### Optional:

<SinceBadge version="2.1.0">

* `settings`: Elasticsearch index [settings](https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings)
* `mappings`: [collection mappings](/core/2/guides/essentials/database-mappings)

<DeprecatedBadge version="2.1.0">

* `dynamic`: [dynamic mapping policy](/core/2/guides/essentials/database-mappings#dynamic-mapping-policy) for new fields. Allowed values: `true` (default), `false`, `strict`
* `_meta`: [collection additional metadata](/core/2/guides/essentials/database-mappings#collection-metadata) stored next to the collection
* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch types definitions format](/core/2/guides/essentials/database-mappings#properties-types-definition)

---

## Response

Returns a confirmation that the collection is being created:

```js
{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}
```

---

## Possible errors

- [Common errors](/core/2/api/essentials/errors/handling#common-errors)
- [PreconditionError](/core/2/api/essentials/errors/handling#preconditionerror)

<commit_msg>[documentation] fix badge tags not closed<commit_after>---
code: true
type: page
title: create
---

# create

<SinceBadge version="1.0.0"/>

Creates a new [collection](/core/2/guides/essentials/store-access-data), in the provided `index`.

Collection names must meet the following criteria:

* Lowercase only
* Cannot include one of the following characters: `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), `,`, `#`, `:`, `%`, `&`, `.`
* Cannot be longer than 126 bytes (note it is bytes, so multi-byte characters will count towards the 126 limit faster)

You can also provide an optional body with a [collection mapping](/core/2/guides/essentials/database-mappings) allowing you to exploit the full capabilities of our persistent data storage layer.

This method will only update the mapping when the collection already exists.

You can define the collection [dynamic mapping policy](/core/2/guides/essentials/database-mappings#dynamic-mapping-policy) by setting the `dynamic` field to the desired value.

You can define [collection additional metadata](/core/2/guides/essentials/database-mappings#collection-metadata) within the `_meta` root field.

<SinceBadge version="2.1.0"/>

You can also provide Elasticsearch index [settings]((https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings)) when creating a new collection.

---

## Query Syntax

### HTTP

```http
URL: http://kuzzle:7512/<index>/<collection>
Method: PUT
Body:
```

<SinceBadge version="2.1.0"/>

```js
{
  "mappings": {
    "dynamic": "[true|false|strict]",
    "_meta": {
      "field": "value"
    },
    "properties": {
      "field1": {
        "type": "integer"
      },
      "field2": {
        "type": "keyword"
      },
      "field3": {
        "type":   "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  },
  "settings": {
    "analysis" : {
      "analyzer":{
        "content":{
          "type":"custom",
          "tokenizer":"whitespace"
        }
      }
    }
  }
}
```

<DeprecatedBadge version="2.1.0"/>

```js
{
  "dynamic": "[false|true|strict]",
  "_meta": {
    "field": "value"
  },
  "properties": {
    "field1": {
      "type": "integer"
    },
    "field2": {
      "type": "keyword"
    },
    "field3": {
      "type":   "date",
      "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
    }
  }
}
```

### Other protocols

<SinceBadge version="2.1.0"/>

```js
{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "body": {
    "mappings": {
      "dynamic": "[true|false|strict]",
      "_meta": {
        "field": "value"
      },
      "properties": {
        "field1": {
          "type": "integer"
        },
        "field2": {
          "type": "keyword"
        },
        "field3": {
          "type":   "date",
          "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
        }
      }
    },
    "settings": {
      "analysis" : {
        "analyzer":{
          "content":{
            "type":"custom",
            "tokenizer":"whitespace"
          }
        }
      }
    }
  }
}
```

<DeprecatedBadge version="2.1.0"/>

```js
{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "body": {
    "dynamic": "[true|false|strict]",
    "_meta": {
      "field": "value"
    },
    "properties": {
      "field1": {
        "type": "integer"
      },
      "field2": {
        "type": "keyword"
      },
      "field3": {
        "type":   "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  }
}
```


---

## Arguments

- `collection`: name of the collection to create
- `index`: index name

---

## Body properties

### Optional:

<SinceBadge version="2.1.0"/>

* `settings`: Elasticsearch index [settings](https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings)
* `mappings`: [collection mappings](/core/2/guides/essentials/database-mappings)

<DeprecatedBadge version="2.1.0"/>

* `dynamic`: [dynamic mapping policy](/core/2/guides/essentials/database-mappings#dynamic-mapping-policy) for new fields. Allowed values: `true` (default), `false`, `strict`
* `_meta`: [collection additional metadata](/core/2/guides/essentials/database-mappings#collection-metadata) stored next to the collection
* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch types definitions format](/core/2/guides/essentials/database-mappings#properties-types-definition)

---

## Response

Returns a confirmation that the collection is being created:

```js
{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "collection",
  "action": "create",
  "requestId": "<unique request identifier>",
  "result": {
    "acknowledged": true
  }
}
```

---

## Possible errors

- [Common errors](/core/2/api/essentials/errors/handling#common-errors)
- [PreconditionError](/core/2/api/essentials/errors/handling#preconditionerror)


{'fraction_non_alphanumeric': 0.18458080906781318, 'fraction_numerical': 0.012311901504787962, 'mean_word_length': 2.9701318851823117, 'pattern_counts': {'":': 150, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '668309', 'n_tokens_mistral': 3455, 'n_tokens_neox': 3338, 'n_words': 729}