---
title: "获取索引映射"
date: 2026-03-22
lastmod: 2026-03-22
description: "获取索引的映射定义，查看字段结构和类型"
tags: ["索引管理", "映射管理", "元数据"]
summary: "获取索引的映射（mapping）定义，查看字段结构、类型和配置。
API #  GET /{index}/_mapping GET /_mapping GET /{index}/_mapping/{type} GET /_mapping/{type} HEAD /{index}/_mapping/{type} API 的作用 #  该 API 用于获取索引的映射信息，可以查看：
 字段名称和数据类型 字段的分析器配置 字段的多字段定义 动态映射设置 元数据配置  映射信息包括 #     信息 描述     properties 所有字段的定义   dynamic 动态映射规则   dynamic_templates 动态模板定义   _meta 映射元数据   runtime 运行时字段定义    API 的参数 #  路由参数 #     参数 类型 是否必填 描述     {index} 字符串 否 索引名称，支持单个索引、逗号分隔的多个索引、通配符表达式、_all（所有索引）   {type} 字符串 否 类型名称（已弃用，从 Easysearch 7."
---


获取索引的映射（mapping）定义，查看字段结构、类型和配置。

## API

```
GET /{index}/_mapping
GET /_mapping
GET /{index}/_mapping/{type}
GET /_mapping/{type}
HEAD /{index}/_mapping/{type}
```

## API 的作用

该 API 用于获取索引的映射信息，可以查看：

- 字段名称和数据类型
- 字段的分析器配置
- 字段的多字段定义
- 动态映射设置
- 元数据配置

### 映射信息包括

| 信息 | 描述 |
|------|------|
| `properties` | 所有字段的定义 |
| `dynamic` | 动态映射规则 |
| `dynamic_templates` | 动态模板定义 |
| `_meta` | 映射元数据 |
| `runtime` | 运行时字段定义 |

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `{index}` | 字符串 | 否 | 索引名称，支持单个索引、逗号分隔的多个索引、通配符表达式、`_all`（所有索引） |
| `{type}` | 字符串 | 否 | 类型名称（已弃用，从 Easysearch 7.0 开始类型已被弃用） |

### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `include_type_name` | 布尔值 | 否 | false | 是否在响应中包含类型名称（已弃用） |
| `master_timeout` | 时间值 | 否 | 30s | 等待主节点响应的超时时间 |
| `local` | 布尔值 | 否 | false | 是否只从本地节点获取信息，不从主节点请求 |

## 示例

### 获取单个索引的映射

```bash
GET /my_index/_mapping
```

**响应示例：**

```json
{
  "my_index": {
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        },
        "message": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "level": {
          "type": "keyword"
        }
      }
    }
  }
}
```

### 获取多个索引的映射

```bash
GET /index1,index2/_mapping
```

### 获取所有索引的映射

```bash
GET /_mapping
```

或

```bash
GET /*/_mapping
```

### 使用通配符获取映射

```bash
GET /logs-*/_mapping
```

### 包含类型名称（已弃用）

```bash
GET /my_index/_mapping?include_type_name=true
```

**响应示例：**

```json
{
  "my_index": {
    "mappings": {
      "_doc": {
        "properties": {
          "field1": { "type": "text" }
        }
      }
    }
  }
}
```

### 从本地节点获取

```bash
GET /my_index/_mapping?local=true
```

### 设置主节点超时

```bash
GET /my_index/_mapping?master_timeout=50s
```

### 使用 HEAD 检查映射

```bash
HEAD /my_index/_mapping
```

如果映射存在，返回 `200 OK`；否则返回 `404 Not Found`。

## 响应字段说明

### properties（字段定义）

| 字段 | 描述 |
|------|------|
| `type` | 字段数据类型 |
| `analyzer` | 索引分析器 |
| `search_analyzer` | 搜索分析器 |
| `fields` | 多字段定义 |
| `doc_values` | 是否使用 doc_values |
| `ignore_above` | 忽略超过此长度的值 |
| `norms` | 是否启用评分 norms |
| `index` | 是否可搜索 |
| `store` | 是否单独存储 |

### 映射级别设置

| 字段 | 描述 |
|------|------|
| `dynamic` | 动态映射策略：`true`、`false`、`strict` |
| `dynamic_templates` | 动态模板定义 |
| `_meta` | 映射元数据 |
| `numeric_detection` | 是否自动检测数字 |
| `date_detection` | 是否自动检测日期 |
| `dynamic_date_formats` | 动态日期格式列表 |

## 常见字段类型

### 核心类型

| 类型 | 描述 | 映射示例 |
|------|------|----------|
| `text` | 全文搜索 | `{"type": "text"}` |
| `keyword` | 精确值 | `{"type": "keyword"}` |
| `date` | 日期 | `{"type": "date"}` |
| `long` | 整数 | `{"type": "long"}` |
| `double` | 浮点数 | `{"type": "double"}` |
| `boolean` | 布尔值 | `{"type": "boolean"}` |
| `binary` | 二进制 | `{"type": "binary"}` |

### 复杂类型

| 类型 | 描述 | 映射示例 |
|------|------|----------|
| `object` | JSON 对象 | `{"type": "object"}` |
| `nested` | 嵌套对象 | `{"type": "nested"}` |
| `geo_point` | 地理坐标点 | `{"type": "geo_point"}` |
| `geo_shape` | 地理形状 | `{"type": "geo_shape"}` |
| `ip` | IP 地址 | `{"type": "ip"}` |
| `completion` | 完成建议 | `{"type": "completion"}` |

## 使用场景

### 场景 1：查看字段配置

```bash
GET /products/_mapping
```

查看产品索引的字段定义。

### 场景 2：比较多个索引映射

```bash
GET /logs-dev,logs-prod/_mapping
```

比较开发和生产环境的映射差异。

### 场景 3：检查特定字段是否存在

```bash
GET /my_index/_mapping | grep "field_name"
```

### 场景 4：导出映射定义

```bash
GET /my_index/_mapping
```

将响应保存为文件，用于在其他环境重建索引。

## 动态映射策略

| dynamic 值 | 行为 |
|------------|------|
| `true` | 新字段自动添加到映射（默认） |
| `false` | 新字段可索引但不在映射中 |
| `strict` | 新字段会导致文档索引失败 |

### 示例映射

```json
{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "title": { "type": "text" },
      "author": { "type": "keyword" }
    }
  }
}
```

## 响应示例（复杂映射）

```json
{
  "my_index": {
    "mappings": {
      "dynamic": "true",
      "properties": {
        "title": {
          "type": "text",
          "analyzer": "standard",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "author": {
          "type": "object",
          "properties": {
            "name": { "type": "text" },
            "email": { "type": "keyword" }
          }
        },
        "tags": {
          "type": "keyword",
          "copy_to": "all_tags"
        },
        "created_at": {
          "type": "date",
          "format": "yyyy-MM-dd HH:mm:ss||epoch_millis"
        }
      },
      "dynamic_templates": [
        {
          "strings_as_keywords": {
            "match_mapping_type": "string",
            "match": "*_id",
            "mapping": {
              "type": "keyword"
            }
          }
        }
      ]
    }
  }
}
```

## 注意事项

1. **类型已弃用**：从 Easysearch 7.0 开始，映射类型已被弃用，所有新索引使用默认类型 `_doc`
2. **性能考虑**：获取大型索引的映射可能需要较长时间
3. **本地模式**：使用 `local=true` 可以从本地节点快速获取信息，但可能不是最新
4. **HEAD 方法**：用于检查映射是否存在，不返回具体内容
5. **通配符限制**：使用通配符时可能返回大量索引的映射信息