一、字段类型核心差异（新手最易踩坑点） #
| 对比维度 | text 字段 | keyword 字段 |
|---|---|---|
| 分词处理 | 索引时通过分析器（如 IK、标准分词）拆分文本，支持中文 / 多语种分词 📝"Apple iPhone 15 Pro" → [“apple”, “iphone”, “15”, “pro”] | 不分词，原样存储为完整字符串 🔒例：“Apple iPhone 15 Pro” → 仅保留原始值 |
| 索引结构 | 构建倒排索引，支持全文检索和相关性评分 | 存储原始值，支持精确匹配和聚合分析 |
| 查询方式 | 需用 match/match_phrase 查询（分词匹配） | 需用 term/terms 查询（精确匹配） |
| 功能支持 | ❌ 不支持聚合（如分组统计）、排序 支持模糊匹配、拼写容错（fuzziness） | ✅ 支持聚合、排序、过滤❌ 不支持分词匹配 |
| 大小写处理 | 默认转为小写（依分析器配置） | 严格区分大小写（原样匹配） |
关键原理：Easysearch 基于 Lucene 内核，text 字段为「全文检索优化」，keyword 为「精确查询优化」，字段类型直接决定查询逻辑与性能。
二、典型使用场景（新手快速选型指南） #
1. text 字段：适合「全文搜索场景」 #
- 核心场景：用户输入自然语言、需模糊匹配的内容
- 商品标题 / 描述（如电商搜索 “无线耳机” 匹配 “Bluetooth headphones”）
- 文章正文、用户评论（需分词检索关键词）
- 日志详情（需检索具体报错信息）
- 实战示例：
// 正确查询：text字段用match分词匹配
{ "query": { "match": { "product_desc": "无线蓝牙耳机" } } }
- Easysearch 优势：支持本地优化的中文分词（IK 企业版、拼音 / 简繁体转换），比原生 Elasticsearch 更适配中文场景。
2. keyword 字段：适合「精确匹配场景」 #
- 核心场景：需严格匹配、排序或统计的结构化数据
- 状态码（如 “ERROR”/“SUCCESS”）、IP 地址、邮箱
- 分类标签（如商品类目、文章标签）
- 聚合分析（如统计各品牌商品数量）
- 实战示例：
// 正确查询：keyword字段用term精确匹配
{ "query": { "term": { "brand.keyword": "Apple" } } }
// 正确用法：聚合统计各状态日志数量
{ "aggs": { "status_count": { "terms": { "field": "status.keyword" } } } }
- 关键提醒：动态映射下，text 字段会自动生成
.keyword子字段（如name.keyword），可直接用于精确查询。
三、新手 3 大高频误区（避坑指南） #
❌ 误区 1：对 text 字段用 term 查询（如用 term: "Apple" 查 text 类型的商品名）
→ 后果：因 text 已分词为小写，无法匹配原始字符串，返回空结果
✅ 修正：用 match 查询，或改用 .keyword 子字段
❌ 误区 2：对 keyword 字段用 match 查询（如用 match: "error" 查日志状态）
→ 后果：多此一举且性能差（match 会先分词再匹配，而 keyword 未分词）
✅ 修正：直接用 term: { "status.keyword": "ERROR" }
❌ 误区 3：用 text 字段做聚合 / 排序（如统计 text 类型的 “分类” 字段）
→ 后果：报错或结果混乱（text 未开启 fielddata 时不支持聚合）
✅ 修正：改用 keyword 字段或 .keyword 子字段
四、特殊场景解决方案 #
若需同时支持「全文搜索 + 精确匹配」（如商品名既需模糊检索，又需精确排序），可使用 多字段（multi-fields） 配置：
{
"mappings": {
"properties": {
"product_name": {
"type": "text", // 全文搜索用
"fields": {
"keyword": {
// 精确匹配/聚合用
"type": "keyword",
"ignore_above": 256 // 忽略超长字符串
}
}
}
}
}
}
