Update collection schema #

Apply an additive schema diff (new or updated field definitions) to an existing collection. The change is replicated through Raft and every shard engine of the collection picks it up.

Field deletion is not supported by design — a schema diff can only add or update properties.

Examples #

Add a title text field and a non-indexed user.name keyword field to the collection my-collection:

PUT /my-collection/_schema
{
  "diff": {
    "title": { "type": "text", "analyzer": "standard" },
    "user.name": { "type": "keyword", "index": false }
  }
}

Switch the schema-level default layout profile of the collection (no field changes needed; the new default applies to fields added afterwards, not to fields already in the schema):

PUT /my-collection/_schema
{
  "profile": "metric"
}

The API returns the following result:

{
  "acknowledged": true,
  "collection": "default:my-collection",
  "version": 2
}

Request #

PUT /[<namespace>:]<name>/_schema

Path Parameters #

• <namespace>
  (Optional, string) The namespace which the collection belongs to.
• <name>
  (Required, string) Name of the collection to update.

Request body #

• diff
  (Optional*, object) Keys are field paths (nested fields use parent.child), values follow the same property definition format as the schema of Create a collection. Analyzer names may reference built-in analyzers or this collection’s custom analyzer definitions.

• profile
  (Optional*, string) Schema-level default layout profile — one of standard, metric, search_only, store_only. The default is resolved at admission time: fields in this request’s diff (and future dynamically inferred fields) are stamped with it unless they declare an explicit per-field profile, which always wins. Fields already in the schema are never re-filled — switching the default only affects fields added afterwards. Omitted = unchanged; once set it cannot be cleared, only switched. See Storage layout parameters.

* At least one of diff and profile must be present. An empty diff with no profile is rejected with 400; a malformed property is rejected with 400 mapper_parsing_exception.

Response #

• version — the schema version after the update.