文档、Mapping 与查询

文档操作

以下请求可在 Kibana Dev Tools 中执行：

PUT articles
{
  "mappings": {
    "properties": {
      "title": { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
      "content": { "type": "text" },
      "docId": { "type": "keyword" },
      "authorId": { "type": "keyword" },
      "publishedAt": { "type": "date" }
    }
  }
}

PUT articles/_doc/1
{
  "title": "Elasticsearch 入门",
  "content": "倒排索引支持全文检索",
  "docId": "1",
  "authorId": "u-1001",
  "publishedAt": "2026-08-23T10:00:00+08:00"
}

GET articles/_doc/1

POST articles/_update/1
{
  "doc": {
    "title": "Elasticsearch 核心原理"
  }
}

DELETE articles/_doc/1

生产环境应显式创建 Index Template 或 Mapping，避免动态映射把日期、数字或标识符识别成错误类型。字段类型一旦写入通常不能原地修改，需要新建索引并 Reindex。

text 与 keyword

类型	索引方式	典型用途
text	经过 Analyzer 分词	文章正文、日志消息、全文检索
keyword	作为完整值索引	ID、状态、标签、精确过滤、聚合和排序

同一字符串常采用 Multi-field：主字段用 text 检索，.keyword 子字段用于聚合和排序。不要对高基数字段无条件开启聚合，也不要依赖 Mapping Explosion 接收无限动态字段。

分析器

Analyzer 由 Character Filter、Tokenizer 和 Token Filter 组成。索引阶段与搜索阶段的分析规则应相容，否则用户输入生成的词项可能无法命中索引词项。

POST _analyze
{
  "analyzer": "standard",
  "text": "Elasticsearch powers search"
}

中文检索通常需要额外的中文分析插件或服务。插件版本必须与 Elasticsearch 版本严格匹配；自定义词典变更还需要明确各节点的发布和重载策略。

Query DSL

全文查询会计算相关性，精确过滤不计算分数且更容易缓存：

GET articles/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "content": "倒排索引" } }
      ],
      "filter": [
        { "term": { "authorId": "u-1001" } },
        { "range": { "publishedAt": { "gte": "now-30d" } } }
      ]
    }
  },
  "sort": [
    { "publishedAt": "desc" },
    { "docId": "asc" }
  ]
}

排序游标必须由一组稳定且能唯一确定顺序的字段组成。_id 不提供 Doc Values，不应直接用于排序或聚合；需要把业务 ID 同步保存为 keyword 字段，并将上一页最后一条记录的 sort 值传给 search_after。跨 Refresh 保持一致视图时，再配合 Point in Time 使用。

查询	用途	常见误用
match	对输入分词后全文匹配	用于 ID 或状态精确查询
term	精确匹配索引中的词项	直接查询经过分词的 text
range	数字、日期和范围过滤	对字符串表达的数字做范围比较
bool	组合 must、filter、should、must_not	把无需评分的条件放进 must
multi_match	跨多个全文字段检索	无限制扩展检索字段导致噪声和开销

通配符、正则和前缀查询可能扫描大量词项，尤其应避免以 * 开头的宽泛查询。面向搜索框的前缀建议评估专用字段类型或补全方案。

ES|QL

ES|QL 是面向过滤、转换和分析的管道式查询语言，适合日志探索、统计分析和表格化结果；Query DSL 仍适合精细控制全文相关性和复杂搜索请求。两者不是简单的替代关系。

FROM logs-*
| WHERE service.name == "order-service" AND log.level == "ERROR"
| STATS error_count = COUNT(*) BY error.type
| SORT error_count DESC
| LIMIT 20

ES|QL 的命令与函数仍随小版本快速演进。使用新命令前应检查目标集群版本，避免把开发环境的语法直接用于较旧生产集群。

向量与语义检索

Elasticsearch 除了 BM25 全文检索，还能保存 dense_vector、sparse_vector 并执行 kNN 检索。常见方案包括：

方案	适用场景	主要代价
semantic_text	希望由 Elasticsearch 管理模型、分块和向量生成	需要配置推理服务并确认许可、模型和资源条件
dense_vector + knn	自行生成 Embedding，需要控制模型和向量	应用负责模型一致性、维度和分块
sparse_vector	稀疏语义检索或 ELSER 工作流	需要模型部署和对应推理资源
关键词 + 向量混合检索	同时保留精确词项与语义召回	需要融合、重排和离线评测

向量检索不是把字段类型改为 dense_vector 就结束。还要固定 Embedding 模型版本，评估召回率与延迟，规划 HNSW/量化带来的内存和精度权衡，并为模型升级准备重新生成向量的流程。