上一篇已经启动了本地 Elasticsearch。现在要解决一个更具体的问题:同一条商品数据,怎样既能搜索标题里的“蓝牙耳机”,又能按品牌筛选、按价格排序?
这不是写查询时才决定的。ES 收到数据时,就需要知道哪些内容要拆成词、哪些值应该完整保留。Mapping 定义的正是字段的类型及其索引方式。 如果把价格存成普通字符串,把标题只存成一个完整词,后面的查询就会处处绕路。
本篇使用系列固定的 Elasticsearch 8.14.0 学习环境。所有 http 代码块都在 Kibana → Dev Tools → Console 中执行;依次完成建索引、导入数据和验证,下一篇可以直接复用结果。
1. 先从搜索页面反推字段
假设页面上有一个关键词输入框,旁边可以选择品牌、分类和价格区间,还能按销量排序。把这些需求翻译成字段定义,会比直接记类型表更容易理解。
| 字段 | 页面怎样使用它 | 本系列类型 |
|---|---|---|
productId | 标识商品、辅助排序 | long |
title、description | 全文搜索 | text + cjk |
brand、category、status | 精确筛选 | keyword |
price | 价格范围筛选、排序 | integer,单位为分 |
sales、stock | 销量排序、库存过滤 | integer |
createdAt | 时间筛选与排序 | date |
例如 199 元在索引中写成 19900。后端在进入搜索层前完成元到分的换算,返回页面时再格式化为元;查询中的 10000 到 30000 就表示 100 到 300 元。整个系列都遵守这个约定,避免示例里价格单位前后不一致。
为什么标题是 text,品牌是 keyword
标题 SoundGo 无线蓝牙耳机 需要拆出可搜索的词项,用户只输入其中一部分也可能找到它,所以使用 text。品牌 SoundGo 则是一个筛选值,应当完整保留,所以使用 keyword。
这里的“精确”针对索引中的值。在本篇没有配置 normalizer 的情况下,SoundGo 和 soundgo 是不同的品牌值。text 的分析过程则可能包含小写转换,它们解决的是两类需求。
同一个标题也可能需要完整匹配。我们会给 title 加一个 keyword 子字段:搜索标题用 title,完整标题匹配用 title.keyword。写入 JSON 时仍然只有一个 title,ES 会按两种方式建立索引;不需要额外提交 title.keyword。
2. 一次建立后续文章共用的索引
实际存放数据的索引叫 products-v1,应用通过两个别名访问它:查询用 products-read,写入用 products-write。现在它们都指向同一个索引;将来换 Mapping 时,可以新建 products-v2 并切换别名,应用就不必到处修改索引名。
下面是完整定义,创建一次即可。若提示 resource_already_exists_exception,说明同名索引已经存在,应先查看现有 Mapping;重复执行 PUT 创建请求不会覆盖它。
PUT /products-v1{ "settings": { "number_of_shards": 1, "number_of_replicas": 0 }, "mappings": { "dynamic": "strict", "properties": { "productId": { "type": "long" }, "title": { "type": "text", "analyzer": "cjk", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "description": { "type": "text", "analyzer": "cjk" }, "brand": { "type": "keyword" }, "category": { "type": "keyword" }, "status": { "type": "keyword" }, "price": { "type": "integer" }, "sales": { "type": "integer" }, "stock": { "type": "integer" }, "createdAt": { "type": "date" } } }, "aliases": { "products-read": {}, "products-write": { "is_write_index": true } }}这一份定义中还有三个需要理解的取舍。
一个主分片、零副本只用于本地单节点练习。 单节点无法把副本放到另一台节点,设为零可以避免练习时出现副本无法分配的状态,但也意味着没有副本冗余。生产环境的分片、副本需要根据容量和可用性要求规划,见第六篇。
ignore_above: 256 表示过长的标题不会进入这个 keyword 子字段的索引;原始标题仍保留在 _source,title 的全文搜索也不因此关闭。它不是标题长度校验规则。
别名的 read、write 后缀是应用约定,本身不会赋予只读或只写权限。is_write_index: true 明确标记通过写别名提交的文档应落到哪里,权限控制是另外一层配置。
为什么主动关闭自动猜字段
默认的动态 Mapping 会根据收到的数据推断新字段。它适合探索数据,但商品结构已知时,拼写错误也可能被当作新字段接受:原本想写 price,却写成了 pirce。
这里选择 dynamic: strict,让未知字段立即暴露。可以执行下面这个预期失败的请求观察错误,它不会新增商品:
PUT /products-write/_doc/1999{ "productId": 1999, "pirce": 19900}预期返回 strict_dynamic_mapping_exception,指出 pirce 未被定义。如果使用 dynamic: false,未知字段会留在 _source 中,但不会成为可搜索的新字段;它和 strict 的拒绝写入不同。
Mapping 也不能替代业务校验。strict 不会要求每条商品都必须有价格,更不会保证价格为正数或状态属于指定枚举。这些规则仍应由 Java 代码和数据源负责。
3. 先看分词结果,再讨论搜索效果
本系列使用 ES 内置的 cjk,无需安装插件。它会为连续的中日韩文字产生相邻双字词项,可以用来完成学习实验;它并不等于“理解中文语义”,也不是所有商品搜索的最佳选择。
不要凭感觉猜一句话会被切成什么,直接让 ES 展示它:
POST /products-v1/_analyze{ "field": "title", "text": "SoundGo 无线蓝牙耳机"}关注响应 tokens 数组中的 token,本例的词项是:
soundgo / 无线 / 线蓝 / 蓝牙 / 牙耳 / 耳机再把 text 换成用户要输入的 蓝牙耳机,会得到 蓝牙 / 牙耳 / 耳机。这解释了两件事:SoundGo 会变为小写;牙耳 这样不符合词典习惯的组合也会出现,因为这里采用的是相邻双字切分。
字段的 analyzer 用于建立索引。全文查询通常也会分析用户输入;没有单独配置 search_analyzer 时,本例沿用 cjk,使两端的词项可以对应起来。以后要使用不同的搜索分析器,应拿真实关键词和商品样本验证召回结果,不能仅凭“索引切细、搜索切粗”就认定效果更好。
如果后续发现品牌别称、型号、同义词搜索不理想,再考虑其他分析器、词典和查询策略。排查的第一步仍然是 _analyze,先确认文档与查询分别产生了什么词项。
4. 导入五条可以核对答案的商品
后面几篇统一使用下面的数据。表中的价格是页面展示的元,写入 JSON 时使用分。
| ID | 标题 | 价格(元) | 销量 | 状态 |
|---|---|---|---|---|
| 1001 | SoundGo 无线蓝牙耳机 | 199 | 3000 | ON_SALE |
| 1002 | SoundGo 便携蓝牙音箱 | 299 | 1200 | ON_SALE |
| 1003 | GameMax 有线游戏耳机 | 99 | 5000 | ON_SALE |
| 1004 | SoundGo 降噪蓝牙耳机 | 399 | 800 | OFF_SALE |
| 1005 | AirBeat 无线蓝牙耳机 | 259 | 1800 | ON_SALE |
Bulk API 一次发送多条写入操作。下面每两行是一组:第一行说明动作和文档 _id,第二行是商品内容。它是 NDJSON,不是外面再套一层数组的普通 JSON;最后一条文档后也要保留换行。
POST /products-write/_bulk?refresh=wait_for{"index":{"_id":"1001"}}{"productId":1001,"title":"SoundGo 无线蓝牙耳机","description":"轻巧便携,适合日常通勤。","brand":"SoundGo","category":"数码耳机","price":19900,"sales":3000,"stock":80,"status":"ON_SALE","createdAt":"2025-07-01T10:00:00+08:00"}{"index":{"_id":"1002"}}{"productId":1002,"title":"SoundGo 便携蓝牙音箱","description":"小巧音箱,适合室内音乐播放。","brand":"SoundGo","category":"数码音箱","price":29900,"sales":1200,"stock":30,"status":"ON_SALE","createdAt":"2025-07-01T10:00:00+08:00"}{"index":{"_id":"1003"}}{"productId":1003,"title":"GameMax 有线游戏耳机","description":"有线连接,配备游戏语音麦克风。","brand":"GameMax","category":"数码耳机","price":9900,"sales":5000,"stock":50,"status":"ON_SALE","createdAt":"2025-07-01T10:00:00+08:00"}{"index":{"_id":"1004"}}{"productId":1004,"title":"SoundGo 降噪蓝牙耳机","description":"支持主动降噪,当前已经下架。","brand":"SoundGo","category":"数码耳机","price":39900,"sales":800,"stock":0,"status":"OFF_SALE","createdAt":"2025-07-01T10:00:00+08:00"}{"index":{"_id":"1005"}}{"productId":1005,"title":"AirBeat 无线蓝牙耳机","description":"适合运动,附带充电盒。","brand":"AirBeat","category":"数码耳机","price":25900,"sales":1800,"stock":60,"status":"ON_SALE","createdAt":"2025-07-01T10:00:00+08:00"}时间统一带 +08:00,避免同一个“上午十点”被不同应用解释成不同的时刻。_id 是 ES 文档标识,productId 是文档里的业务字段,两者不会自动同步;本例主动使用相同的商品 ID,便于之后定位和更新。
检查响应中的 errors 是否为 false。Bulk 的 HTTP 请求成功,不代表其中每个动作都成功;如果 errors 为 true,要继续看 items 中各条操作的 status 和 error。
这五条数据使用固定 _id 和 index 动作。重新执行会替换同 ID 的文档,可以恢复修改过的样本,不会再多出五条商品;它不会清理你额外写入的其他 ID。
5. 写入成功,为什么搜索还可能看不到
通过 ID 读取商品:
GET /products-read/_doc/1001预期看到 found: true 和商品的 _source。再检查搜索可见的文档数量:
GET /products-read/_count只导入本篇数据时,预期 count 为 5。如果数量不同,先检查 Bulk 的逐条结果,以及索引里是否还有其他练习数据。
这里容易混淆两个动作:按 ID 的 GET 默认是实时读取;_search 和 _count 依赖已经 refresh 的搜索视图。 所以普通写入返回成功后,GET 可以看到最新文档,搜索却可能暂时看不到。这不是两条请求读到了不同数据库,而是读取方式不同。
本次 Bulk 加上 refresh=wait_for,就是等待这些变化对搜索可见后再返回,方便紧接着验证。它通常等待一次 refresh,而不是像 refresh=true 那样主动要求立即刷新。不要为了省去等待,在每次生产写入后都强制刷新;刷新频率与性能的取舍放到第六篇讨论。
如果要确认当前的字段与别名,可以分别执行:
GET /products-v1/_mapping
GET /products-v1/_alias这两个响应比“我记得当时建的是这个类型”可靠。尤其在切换环境或复用旧索引时,应先查看真实定义。
6. 对象数组什么时候需要 nested
前面的商品只有简单字段。现在假设商品有多个 SKU,其中一款是“红色、M 码”,另一款是“蓝色、L 码”。用户要求“红色、L 码”时,这件商品不应该命中,因为没有同一个 SKU 同时满足条件。
普通 object 数组在索引时会失去数组元素之间的配对关系。颜色里有红色、尺码里有 L,就可能组合出一次错误匹配。需要保持“同一个数组元素内同时满足”时,可以使用 nested。
下面使用独立的练习索引,不改变五条商品样本:
PUT /sku-demo{ "settings": { "number_of_shards": 1, "number_of_replicas": 0 }, "mappings": { "properties": { "skus": { "type": "nested", "properties": { "color": { "type": "keyword" }, "size": { "type": "keyword" } } } } }}
PUT /sku-demo/_doc/1?refresh=wait_for{ "skus": [ { "color": "红色", "size": "M" }, { "color": "蓝色", "size": "L" } ]}
GET /sku-demo/_search{ "query": { "nested": { "path": "skus", "query": { "bool": { "filter": [ { "term": { "skus.color": "红色" } }, { "term": { "skus.size": "L" } } ] } } } }}预期命中数为 0;把查询尺码改成 M 后,预期命中商品 1。先记住这个区别即可:nested 外层指定数组路径,里面的条件约束同一个嵌套元素。下一篇会展开 bool 和 term 的语法。
nested 会把嵌套对象作为额外的隐藏文档索引,带来存储和查询成本。普通对象、字符串标签数组,或无需关联数组内部条件的场景,不必为了“更完整”全部使用它。
7. 字段设计错了,怎样修正
Mapping 可以新增字段,也允许调整部分参数,但已经建立索引的字段类型通常不能原地替换。例如把 brand 从 text 改成 keyword,或者改变标题的索引分析方式,都涉及如何重新解释已有数据。
通常的处理流程是:用新定义建立 products-v2,重新导入或重建数据,验证查询结果,再将读写别名切过去。新 Mapping 不会自动重写旧数据,别名切换也不会自动补齐迁移期间的增量;第五篇会把这两个问题一起讲清楚。
学完本篇,可以用三个结果检查是否准备好进入查询阶段:_mapping 显示标题为使用 cjk 的 text、价格为整数;_analyze 能解释关键词如何拆分;_count 为 5。以后遇到“搜不到”的问题,就从这三处逐层排查。
参考资料
- Elastic 8.14:动态字段处理方式
- Elastic 8.14:内置语言分析器与 cjk
- Elastic 8.14:refresh 参数
- Elastic 8.14:别名 API
- Elastic 8.14:nested 与对象数组的关系
If this article helped you, please share it with others!
Some information may be outdated






