更新索引映射

更新一个或多个索引的映射定义，添加新字段或修改现有字段配置。

API #

PUT /{index}/_mapping
POST /{index}/_mapping

API 的作用 #

该 API 用于更新索引的映射（mapping）定义，支持以下操作：

添加新字段：为索引添加新的字段及其类型定义
更新字段配置：修改某些字段的可更新属性
合并映射：新的映射定义会与现有映射合并

映射更新的限制 #

操作	是否支持	说明
添加新字段	是	可以随时添加
修改字段类型	否	已有字段不能修改类型
修改字段名称	否	不能重命名字段
删除字段	否	不能删除已有字段
更新分析器	有限	某些分析器设置可以更新
添加别名	是	可以添加字段别名

API 的参数 #

路由参数 #

参数	类型	是否必填	描述
`{index}`	字符串	否	索引名称列表，逗号分隔。支持通配符、`_all`（所有索引）

Query String 参数 #

参数	类型	是否必填	默认值	描述
`timeout`	时间值	否	30s	显式操作超时时间
`master_timeout`	时间值	否	30s	连接到主节点的超时时间
`include_type_name`	布尔值	否	false	是否在请求体中包含类型名称（已弃用）
`ignore_unavailable`	布尔值	否	false	是否忽略不可用的索引
`allow_no_indices`	布尔值	否	false	是否允许通配符解析为空索引
`expand_wildcards`	枚举值	否	open	通配符展开选项。可选值：`open`、`closed`、`hidden`、`none`、`all`
`write_index_only`	布尔值	否	false	是否仅应用于别名的写索引

请求体参数（必需） #

请求体必须包含映射定义。支持两种格式：

无类型模式（推荐） #

{
  "properties": {
    "field1": {
      "type": "text",
      "analyzer": "standard"
    },
    "field2": {
      "type": "keyword"
    }
  }
}

有类型模式（已弃用） #

当 include_type_name=true 时使用：

{
  "type_name": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}

常见字段类型 #

类型	描述	示例
`text`	全文搜索文本	`"type": "text"`
`keyword`	精确值（ID、标签等）	`"type": "keyword"`
`date`	日期时间	`"type": "date"`
`long`	64位整数	`"type": "long"`
`double`	64位浮点数	`"type": "double"`
`boolean`	布尔值	`"type": "boolean"`
`object`	JSON 对象	`"type": "object"`
`nested`	嵌套对象	`"type": "nested"`
`ip`	IP 地址	`"type": "ip"`

示例 #

添加新字段 #

PUT /my_index/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    },
    "created_at": {
      "type": "date"
    }
  }
}

响应示例：

{
  "acknowledged": true
}

更新多个索引的映射 #

PUT /index1,index2/_mapping
{
  "properties": {
    "status": {
      "type": "keyword"
    }
  }
}

使用通配符更新 #

PUT /logs-*/_mapping
{
  "properties": {
    "log_level": {
      "type": "keyword"
    }
  }
}

添加带分析器的文本字段 #

PUT /my_index/_mapping
{
  "properties": {
    "content": {
      "type": "text",
      "analyzer": "standard",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256
        }
      }
    }
  }
}

添加对象字段 #

PUT /my_index/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": { "type": "text" },
        "email": { "type": "keyword" }
      }
    }
  }
}

添加嵌套字段 #

PUT /my_index/_mapping
{
  "properties": {
    "comments": {
      "type": "nested",
      "properties": {
        "user": { "type": "keyword" },
        "message": { "type": "text" }
      }
    }
  }
}

设置动态模板 #

PUT /my_index/_mapping
{
  "dynamic_templates": [
    {
      "strings_as_keywords": {
        "match_mapping_type": "string",
        "match": "*_id",
        "mapping": {
          "type": "keyword"
        }
      }
    }
  ]
}

更新动态映射设置 #

PUT /my_index/_mapping
{
  "dynamic": "strict",
  "properties": {
    "new_field": { "type": "text" }
  }
}

只更新打开的索引（默认） #

PUT /*/_mapping?expand_wildcards=open
{
  "properties": {
    "timestamp": { "type": "date" }
  }
}

只应用于写索引 #

PUT /logs_write/_mapping?write_index_only=true
{
  "properties": {
    "tag": { "type": "keyword" }
  }
}

字段属性 #

通用属性 #

属性	类型	描述
`type`	字符串	字段数据类型
`doc_values`	布尔值	是否使用 doc_values（默认多数类型为 true）
`ignore_above`	整数	超过此长度的值不索引（keyword 类型）
`copy_to`	字符串/数组	复制字段值到目标字段

文本字段属性 #

属性	类型	描述
`analyzer`	字符串	索引分析器
`search_analyzer`	字符串	搜索分析器
`norms`	布尔值	是否启用评分 norms
`index`	布尔值	是否字段可搜索
`store`	布尔值	是否单独存储

数值字段属性 #

属性	类型	描述
`coerce`	布尔值	是否强制类型转换
`ignore_malformed`	布尔值	是否忽略格式错误

错误处理 #

映射冲突 #

{
  "error": {
    "type": "mapper_parsing_exception",
    "reason": "failed to parse mapping [field1]",
    "caused_by": {
      "type": "illegal_argument_exception",
      "reason": "cannot change parameter [type] from [text] to [keyword]"
    }
  }
}

索引不存在 #

{
  "error": {
    "type": "index_not_found_exception",
    "reason": "no such index [my_index]"
  }
}

使用场景 #

场景 1：逐步构建映射 #

# 创建索引时定义基本映射
PUT /my_index
{
  "mappings": {
    "properties": {
      "title": { "type": "text" }
    }
  }
}

# 后续添加新字段
PUT /my_index/_mapping
{
  "properties": {
    "category": { "type": "keyword" },
    "tags": { "type": "keyword" }
  }
}

场景 2：添加多字段 #

PUT /products/_mapping
{
  "properties": {
    "name": {
      "type": "text",
      "fields": {
        "raw": { "type": "keyword" },
        "english": { "type": "text", "analyzer": "english" }
      }
    }
  }
}

场景 3：批量更新多个索引 #

PUT /logs-2024-*,logs-2025-*/_mapping
{
  "properties": {
    "hostname": { "type": "keyword" }
  }
}

注意事项 #

类型不可变：已有字段的数据类型不能修改
已索引数据：映射更新不影响已索引的数据
动态映射：禁用动态映射（dynamic: strict）时只能通过 API 添加字段
性能影响：更新映射会触发索引重建某些数据结构
测试优先：建议在测试环境验证映射变更后再应用到生产

标签

索引管理映射管理字段定义