在使用 Easysearch 的过程中，很多开发者都会遇到这样的问题：
为什么同样的数据，搜索结果不一致？
为什么字段不能排序或聚合？
为什么写入一段时间后，索引变得越来越“难维护”？
这些问题，大多都与一个核心概念有关——映射（Mapping）。
本文将从入门视角出发，系统介绍 Easysearch 中 Mapping 的作用、字段数据类型、动态映射机制，以及如何查看和修改映射，帮助你在一开始就把数据结构设计清楚。
一、Easysearch 是什么？ #
Easysearch 是一款面向搜索与分析场景的分布式搜索引擎，适用于日志分析、全文检索、指标统计等多种业务场景。在 Easysearch 中，数据以 JSON 文档 的形式写入索引（Index），而系统之所以能够高效搜索和分析这些数据，关键在于：
- 每个字段是什么类型
- 这些字段是否参与搜索
- 是否支持排序、聚合等操作
这些规则，统一由 Mapping（映射） 来定义。可以简单理解为：Mapping 就是索引中数据的“结构说明书”。
二、什么是 Mapping？ #
Mapping 用来描述 字段的结构和行为，它决定了：
- 字段存储的数据类型（字符串、数字、时间等）
- 是否进行分词（用于全文搜索）
- 是否支持排序、聚合、过滤
如果把索引比作一张表，那么 Mapping 就相当于这张表的“字段定义”。一个最简单的 Mapping 结构示例如下：
{
"mappings": {
"properties": {
"title": {
"type": "text"
},
"created_at": {
"type": "date"
}
}
}
}
在这个例子中：
title是用于全文搜索的文本字段created_at是时间字段，适合做范围查询或时间统计
三、常见字段数据类型介绍 #
Easysearch 提供了多种字段类型，用于应对不同的数据场景。下面介绍几种最常见、也是最容易用到的类型。
1. text：用于全文搜索 #
text 类型会对内容进行分词处理，适合：
- 标题
- 描述
- 评论内容
{
"type": "text"
}
特点是：
- 适合“包含关系”的搜索
- 不适合直接做排序或聚合
2. keyword：用于精确匹配 #
keyword 类型不会分词，适合：
- 用户名
- 状态值
- 枚举字段
{
"type": "keyword"
}
特点是：
- 支持精确匹配
- 支持排序和聚合
3. numeric：数值类型 #
常见的数值类型包括 integer、long、float 等，用于存储：
- 数量
- 金额
- 评分
{
"type": "integer"
}
数值类型字段非常适合用于范围查询和统计分析。
更多数值类型类型请查阅 Easysearch 官方文档
4. date：时间类型 #
date 类型用于存储时间数据，例如：
- 创建时间
- 更新时间
- 事件发生时间
{
"type": "date"
}
它支持时间范围查询和基于时间的聚合分析。
四、动态映射（Dynamic Mapping）是什么？ #
为了降低使用门槛，Easysearch 默认支持 动态映射。
这意味着：当你写入一个新字段，而 Mapping 中尚未定义时，Easysearch 会自动推断字段类型并创建映射。
例如，直接写入以下文档：
{
"user": "alice",
"age": 30
}
如果 user 和 age 尚未定义，系统会自动创建对应字段。
动态映射的优点 #
- 上手简单
- 无需提前设计字段结构
- 适合快速验证和原型阶段
动态映射的风险 #
- 字段类型一旦确定，后续不可修改
- 不同格式的数据可能导致类型冲突
- 字段数量不可控，影响性能和维护成本
因此，在正式业务中，建议明确关键字段的 Mapping，而不是完全依赖动态映射。
关于字符串的动态映射，通常系统自动会动态创建 Multi-fields（多字段），即一个 text 字段带一个 .keyword 子字段。
五、如何查看索引的 Mapping？ #
可以通过索引 Mapping 接口查看当前定义的字段结构：
GET /my_index/_mapping
返回结果中会包含：
- 所有字段名称
- 字段类型
- 相关参数配置
这是排查字段行为是否符合预期时，最常用的手段之一。
六、如何创建和修改 Mapping？ #
1. 创建索引时指定 Mapping #
在创建索引时，一次性定义好字段结构是最推荐的方式：
PUT /my_index
{
"mappings": {
"properties": {
"user": {
"type": "keyword"
},
"message": {
"type": "text"
},
"created_at": {
"type": "date"
}
}
}
}
2. 已有索引中添加新字段 #
对于已存在的索引，可以新增字段：
PUT /my_index/_mapping
{
"properties": {
"status": {
"type": "keyword"
}
}
}
需要注意的是：Easysearch 不允许修改已经存在的字段定义（因为这会破坏已经建好的倒排索引）。如果你发现 age 字段被错误地设为了 keyword 而你想改成 integer，你必须创建一个拥有正确 Mapping 的新索引，并通过 _reindex API 将数据迁移过去
七、实践建议：Mapping 应该怎么设计？ #
对于入门用户，可以遵循以下原则：
- 明确核心字段，提前定义
- 用
text做搜索，用keyword做精确匹配 - 时间字段务必使用
date类型 - 谨慎依赖动态映射，避免字段无限增长
- 定期查看 Mapping，确保字段结构可控
八、总结 #
Mapping 是 Easysearch 中最基础、也最容易被忽视的部分，但它直接决定了：
- 搜索效果是否符合预期
- 聚合和统计是否可用
- 索引是否易于维护
理解并合理设计 Mapping，是从“能用 Easysearch”迈向“用好 Easysearch”的第一步。如果你刚开始接触 Easysearch，建议先把字段结构想清楚，再开始写入数据，这会为后续的搜索和分析省下大量成本。
