---
title: "更新索引映射"
date: 2026-01-26
lastmod: 2026-01-26
description: "更新索引的映射定义，添加或修改字段配置"
tags: ["索引管理", "映射管理", "字段定义"]
summary: "更新一个或多个索引的映射定义，添加新字段或修改现有字段配置。
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 是否仅应用于别名的写索引    请求体参数（必需） #  请求体必须包含映射定义。支持两种格式："
---


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

## 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 | 是否仅应用于别名的写索引 |

### 请求体参数（必需）

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

#### 无类型模式（推荐）

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

#### 有类型模式（已弃用）

当 `include_type_name=true` 时使用：

```json
{
  "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"` |

## 示例

### 添加新字段

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

**响应示例：**

```json
{
  "acknowledged": true
}
```

### 更新多个索引的映射

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

### 使用通配符更新

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

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

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

### 添加对象字段

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

### 添加嵌套字段

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

### 设置动态模板

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

### 更新动态映射设置

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

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

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

### 只应用于写索引

```bash
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` | 布尔值 | 是否忽略格式错误 |

## 错误处理

### 映射冲突

```json
{
  "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]"
    }
  }
}
```

### 索引不存在

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

## 使用场景

### 场景 1：逐步构建映射

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

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

### 场景 2：添加多字段

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

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

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

## 注意事项

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