Create a collection #

Creates a new collection.

Examples #

The following request creates a new collection called my-collection in the namespace my-namespace:

PUT /my-namespace:my-collection

If creating a collection within the default namespace, it can be simplified as:

PUT /my-collection

Request #

PUT /[<namespace>:]<name>

Path parameters #

<namespace>
(Optional, string) The namespace which the collection belongs to. Namespace names must meet the following criteria:
- Lowercase only
- Cannot include \ /, *, ?, ", <, >, |, , ,, #
- Cannot start with -, _, +
- Cannot be . or ..
- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
<name>
(Required, string) Name of the collection you wish to create. Collection names must meet the same criteria as namespace names.

Query parameters #

<wait_for_active_shards> \
(Optional, string) The number of copies of each shard that must be active before proceeding with the operation. Set to all or any non-negative integer up to the total number of copies of each shard in the collection (number_of_replicas+1).
Defaults to 1, meaning to wait just for each primary shard to be active.
<timeout>
(Optional, time units) Period the request waits for the following operations:
- Waiting for active shards
Defaults to 1m (one minute).

Request body #

settings
Collection settings
- rolling.partitions_sharding_strategy
  (Optional, object) Specifies the default value for rolling setting partitions_sharding_strategy, which is used to configure the initial number of primary shards and how partitions are assigned to them for a rolling.
  Default value: create 1 shard and assign all partitions to it.
  Supported strategies are listed below:
  - Hash
```
"hash": {
  "number_of_shards": <num_shards>
}
```
    One can specify the total number of shards, partitions are assigned to shards in this way:
```
shard_index = hash(partition_id) mod number_of_shards
```
  - Range
```
"range": ["0..128, 129..255"]
```
    An array of partition range needs to be provided, every array item represents a shard, the partitions specified in it will be assigned to the shard.
    The above example evenly assigns 256 partitions to 2 shards.
- rolling.number_of_replicas
  (Optional, Integer) Specify the default value for rolling setting number_of_replicas, which controls the number of replicas a primary shard will have. Defaults to 1.
- routing.allocation
  (Optional, object) Shard-routing allocation policy for the collection’s shard copies:
```
"routing": {
  "allocation": {
    "total_shards_per_node": 1,
    "include": { "_id": "node-a,node-b" },
    "exclude": { "_id": "node-c" }
  }
}
```
  - total_shards_per_node — (Optional, integer >= 1) Cap on the number of the collection’s shard copies placed on a single node.
  - include._id — (Optional, string) Comma-separated node ids; copies are only placed on these nodes.
  - exclude._id — (Optional, string) Comma-separated node ids that are never chosen.
  The policy applies to every placement decided afterwards (new rollings, replica top-up, relocations), and the allocation service relocates existing replica copies that violate it. It can be changed later with Update collection settings.
- analysis.analyzer.default.type
  (Optional, string) Collection-level default index analyzer, for text fields only.
- analysis.analyzer.default_search.type
  (Optional, string) Collection-level default search analyzer, for text fields only.
- analysis.analyzer.custom
  (Optional, object) Named custom analyzer definitions for this collection. Each entry is an ordered list of normalizers applied to the raw text, one tokenizer, and an ordered list of token filters; schema properties reference the analyzer by its name exactly like a built-in one:
```
"analysis": {
  "analyzer": {
    "custom": {
      "my_analyzer": {
        "normalizers": ["lowercase_ascii"],
        "tokenizer": "standard",
        "token_filters": ["asciifolding"]
      }
    }
  }
}
```
schema
Initial collection schema
- dynamic
  (Optional, Dynamic) Controls whether new fields are added dynamically.
  Available options:
  - true: New fields are added to the schema (default).
  - false: These fields will not be indexed or searchable, but will still appear in the _source field of returned hits. These fields will not be added to the schema, and new fields must be added explicitly.
  - strict: If new fields are detected, an exception is thrown and the document is rejected. New fields must be explicitly added to the schema.
- profile
  (Optional, string) Schema-level default layout profile — one of standard, metric, search_only, store_only. Stamped at create time onto every field of the initial schema (and applied to fields admitted later) unless the field declares an explicit per-field profile, which always wins; readback schemas therefore show the resolved per-field profile.
  Default value: unset — each field falls back to its per-type default. Once set it cannot be cleared, only switched; switching affects only fields added afterwards (see Update collection schema).
  For the meaning of each profile see Storage layout parameters.
- properties
  (Optional, object) Initial fields properties.
  Default value: no properties will be set.
  Example value:
```
"properties": {
  "id": {
    "type": "integer"
  },
  "history": {
    "type": "text",
    "analyzer": "standard",
    "search_analyzer": "whitespace"
  },
  "body": {
    "type": "text",
    "fields": {
      "embedding": {
        "type": "dense_vector",
        "vector_options": { "model": "text-embedding-3-small", "dims": 1536 }
      }
    }
  }
}
```
  The body field above declares a semantic multi-field: plain-text writes to body are embedded server-side into body.embedding at index time (the model must be configured under an embedding endpoint first — see vector search).
  For more information about the types supported by Pizza, please refer to Field types.