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.

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.

  • 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.

• 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.

  • 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"
      }  
    }