Elasticsearch 9.x 从入门到精通(4/7):聚合分析与文本分析

系列文章 :《Elasticsearch 9.x 从入门到精通》共 7 篇,本篇为第 4 篇,覆盖第 17~20 章。

基线 :Elasticsearch 9.x 源码 main 分支(34eafb4ac58d,Version.CURRENT = V_9_7_0)与官方全量文档。

写作纪律 :每个知识点标注官方文档出处,涉及实现原理均给出源码锚点 路径:行号,禁止编造 API。

本篇目录

  • 第 17 章 聚合框架:桶、指标、管道与矩阵
  • 第 18 章 桶聚合全解(bucket)
  • 第 19 章 指标聚合与管道聚合(metrics/pipeline)
  • 第 20 章 文本分析(text analysis)全栈

第 17 章 聚合框架:桶、指标、管道与矩阵

出处:refs/official-docs/reference/aggregations/index.md、bucket.md、

metrics.md、pipeline.md;refs/docs-content/explore-analyze/query-filter/aggregations.md

源码:server/src/main/java/org/elasticsearch/search/aggregations/

17.1 聚合执行模型

Elasticsearch 聚合框架分三类:metric 从字段或脚本值计算统计量;

bucket 按条件划分文档集;pipeline 不直接处理文档,而是消费其他

聚合的输出。请求通常写成:

http 复制代码
POST sales/_search
{
  "size": 0,
  "query": {
    "range": { "date": { "gte": "now-30d" } }
  },
  "aggs": {
    "by_status": {
      "terms": { "field": "status" }
    }
  }
}

size: 0 表示不取回 hits,只返回 aggregations。聚合和查询是两个独立阶段:

先由 query 圈定文档集,再在匹配文档上收集聚合。官方示例也强调:想限制所有

聚合的输入,优先写顶层 query,而不是把文档包在一个 filter 聚合里

(search-aggregations-bucket-filter-aggregation.md)。

源码执行链路:

text 复制代码
REST/SearchSourceBuilder
  → AggregatorFactories.createTopLevelAggregators()
  → ContextIndexSearcher.search(query, BucketCollector)
  → 每个 leaf/segment: Aggregator.collect(doc, owningBucketOrd)
  → 分片内部分段结果 partial reduce
  → 协调节点合并各分片 InternalAggregations
  → final reduce 后执行 pipeline aggregator

关键源码锚点:

  • AggregationPhase.java:28 注册聚合预处理;:61 创建顶层 aggregator;
    :67 明确捕获过深嵌套导致的 StackOverflowError;
  • Aggregator.java:36 定义聚合器基类;LeafBucketCollector.java:75 的
    collect(int doc, long owningBucketOrd) 是逐文档进入聚合树的入口;
  • AggregatorCollectorManager.java:44 在多个 slice 间做 partial reduce;
    :50 调用 InternalAggregations.topLevelReduce();
  • InternalAggregations.java:255 是协调节点 reduce 的入口;
    AggregatorsReducer.java:46 按聚合名依次 accept(),:59 产出结果;
  • SearchPhaseController.java:652 构造 reduce context,:669 对只计数、
    无聚合的请求启用更轻的消费路径。

分片返回的是近似和可序列化的中间结果。例如 terms 只返回每分片

shard_size 个候选桶,协调节点再合并 top size;因此文档数可能有小误差。

这个语义不是实现缺陷,而是分布式聚合的默认取舍,第 18 章会展开。

桶数上限

单个响应内的桶数量受集群设置 search.max_buckets 限制,默认 65,536。

源码注释和设置定义在

MultiBucketConsumerService.java:30-35,超限时抛出

TooManyBucketsException。该限制按响应中的桶计算,嵌套聚合会快速放大总量;

不要把"分页取所有桶"用大 size 硬扛,terms 用 composite,时间序列优先

走 ES|QL 或固定时间窗口。

17.2 聚合树与命名规则

JSON 里 aggs 是 aggregations 的缩写。聚合树规则如下:

  1. 同名作用域唯一 :同一父聚合下,聚合名不能重复;不同分支可以重名,
    但响应路径不同,不建议这样写。
  2. 只有桶聚合能带子聚合 :metric 聚合输出统计值,pipeline 聚合输出
    后处理结果;两者不能继续嵌套子聚合。
  3. pipeline 无子聚合,但可引用 pipeline :pipeline.md 明确指出 pipeline
    不接受子聚合,不过 buckets_path 可以引用另一个 pipeline,从而形成
    二阶导数这类链式计算。
  4. 路径是相对路径 :buckets_path 从当前 pipeline 所在位置出发,不能向上
    回溯。a>b.avg 表示进入子桶聚合 a,再取多值 metric b.avg。
  5. 嵌套文档先切上下文 :nested 聚合切换到 nested 子文档上下文;如果要
    回到父文档,用 reverse_nested,否则子聚合仍在 nested 文档上执行。

典型聚合树:

http 复制代码
POST orders/_search
{
  "size": 0,
  "aggs": {
    "regions": {
      "terms": { "field": "region", "size": 10 },
      "aggs": {
        "monthly": {
          "date_histogram": {
            "field": "created_at",
            "calendar_interval": "month"
          },
          "aggs": {
            "revenue": { "sum": { "field": "amount" } }
          }
        }
      }
    }
  }
}

响应会保留树的形状:aggregations.regions.buckets[].monthly.buckets[].revenue.value。

名字承担两条职责:定义响应路径;供排序或 buckets_path 引用。因此名字应稳定、

可读、避免和字段名混用。

17.3 执行提示与 collect 模式

collect_mode:深度优先还是广度优先

collect_mode 控制"什么时候展开子聚合":

模式 行为 适合
depth_first 每遇到一个父桶,立即展开其子聚合 子聚合数量可控、结果不需先裁剪父桶
breadth_first 先收集父桶、裁剪出 top 桶,再对保留桶重放子聚合 高基数 terms、想避免桶爆炸

官方 terms 文档给出的典型例子是"10 个热门演员,每个演员取 5 个合作演员"。

如果用深度优先,可能为大量候选演员都展开子树,最后只保留少数结果;

广度先先裁剪父桶,代价是需要缓存文档集合用于第二遍重放。

terms 文档说明:breadth_first 的默认条件是字段基数大于请求 size 或

基数未知;其内存开销与匹配文档数线性相关。

源码锚点:

  • Aggregator.java:204 定义 collect_mode 解析字段;
  • TermsAggregationBuilder.java:110-111 保存 execution_hint 与 collect_mode;
  • TermsAggregator.java:193 保存 SubAggCollectionMode,:223 在未显式指定时
    可落为 DEPTH_FIRST,:271 判断广度优先下子聚合是否需要特殊执行。

不要把 collect_mode 当成万能开关。它只在某些桶聚合上有效;sampler、

diversified_sampler 需要 score,不能嵌套在丢弃 score 的 breadth_first

terms 下面(sampler 和 diversified_sampler 文档均有警告)。

execution_hint:桶怎么构造

execution_hint 是另一个层次的提示,指"用什么索引结构形成桶":

聚合 常见 hint 说明
terms / significant_terms map、global_ordinals keyword 默认 global ordinals;脚本用 map;官方建议一般不显式设置
cardinality direct、global_ordinals、segment_ordinals、save_time_heuristic、save_memory_heuristic 8.4+ 默认 save_time_heuristic
sampler / diversified_sampler 各自 ExecutionMode 需按字段类型和采样字段选择

map 直接按文档值入 map,适合很少量匹配文档;global_ordinals 依赖字段全局

字典,对 keyword 很快,但字段或聚合范围变化时可能触发构建。全局序数构建成本

可以在索引侧通过 eager_global_ordinals 预热,但这是空间/写入时间换查询时间。

源码锚点:

  • TermsAggregationBuilder.java:49 定义 execution_hint;
  • TermsAggregatorFactory.java:110-111 解析用户 hint;
  • CardinalityAggregationBuilder.java:46-47 定义 precision_threshold 和
    execution_hint;
  • CardinalityAggregatorFactory.java:151 未指定时选择
    SAVE_TIME_HEURISTIC。

17.4 矩阵统计的位置

matrix_stats 在官方 TOC 中挂在 aggregations 域,但行为上是多字段 metric

聚合:输入多个数值字段,输出 count、mean、variance、covariance、correlation

等矩阵信息。它不是"把多个字段拼接成一个桶键";那类需求用 multi_terms 或

composite。

源码锚点:MatrixStatsAggregationBuilder.java:27、

MatrixStatsAggregator.java、RunningStats.java。本章只确定它在执行模型中的

位置;公式与用法在第 19 章展开。

17.5 性能与排障

按优先级处理聚合性能:

  1. 先查询,后聚合 :能用时间范围、term/range 过滤收窄数据集的,不要用
    聚合分支假装过滤。
  2. 选对字段 :聚合/排序字段应有 doc values;keyword 子字段优先于开启
    fielddata 的 text 字段。
  3. 控制候选桶 :先估计基数,再设置 size、shard_size、min_doc_count;
    全量遍历用 composite 分页。
  4. 观察近似信号 :sum_other_doc_count、doc_count_error_upper_bound
    非零时不要把结果当精确值。
  5. 警惕 runtime 字段:能索引成 keyword/numeric 就不要每次查询跑脚本。
  6. 限制深度 :聚合树不是树状数据库。过深嵌套会让查询计划难以推理,
    源码也在构建阶段防御过深树(AggregationPhase.java:67)。

排障口径:

现象 先查
max_buckets 报错 是否大 size terms、宽时间窗直方图、高基数 nested 组合
结果不稳定 是否依赖分片近似;shard_size 是否过小;是否用了近似 metric
keyword 聚合慢 global ordinals 是否反复构建;是否应合并低基数字段或预聚合
结果少 是否 min_doc_count 过高;breadth_first 是否裁剪掉父桶
pipeline 没出现 是否放在错误的层级;buckets_path 是否相对;目标聚合是否真的存在

第 18 章 桶聚合全解(bucket)

出处:refs/official-docs/reference/aggregations/bucket.md 及其 33 个聚合子页;

分布式语义重点见 search-aggregations-bucket-terms-aggregation.md、

search-aggregations-bucket-composite-aggregation.md

源码:server/src/main/java/org/elasticsearch/search/aggregations/bucket/

桶聚合回答"文档落在哪些集合里"。它本身通常至少输出 doc_count,并可继续

挂 metric、bucket 或 pipeline 子聚合。本章按官方 TOC 覆盖 33 个桶聚合,

不把 range-field-note 这类说明页算作聚合。

18.1 家族总表

家族 聚合
词条类 terms、multi_terms、rare_terms、significant_terms、significant_text
条件与作用域 filter、filters、missing、global
区间类 range、date_range、ip_range、ip_prefix、geo_distance
直方图类 histogram、date_histogram、auto_date_histogram、variable_width_histogram
游标遍历 composite
地理网格 geohash_grid、geotile_grid、geohex_grid
文档关系 nested、reverse_nested、children、parent
采样类 sampler、diversified_sampler、random_sampler
关联矩阵 adjacency_matrix
x-pack / ML categorize_text、time_series、frequent_item_sets

选择原则:

  • 想看"哪些值/组合",先 terms 或 multi_terms;
  • 想稳定遍历所有值/组合,不要把 terms.size 调成天文数字,用 composite;
  • 想看异常分布,用 rare_terms 或 significant_terms;
  • 文本是未切分的半结构化日志,用 categorize_text;
  • 地图渲染用 geo grid;地图后端不要在高缩放级别下无界聚合全球数据;
  • 深度学习式自由文本,significant_text 必须配采样;
  • 时序监控优先 ES|QL TS;time_series 在 9.7+ 已标记 deprecated。

18.2 terms 族

terms

terms 为字段唯一值创建桶,默认返回 top 10。keyword、numeric、ip、boolean、

binary 可直接聚合;text 默认不能聚合,除非显式开启 fielddata,官方文档

明确警告这会显著增加内存。常用参数:

http 复制代码
GET sales/_search
{
  "size": 0,
  "aggs": {
    "status": {
      "terms": {
        "field": "status",
        "size": 20,
        "shard_size": 50,
        "min_doc_count": 1,
        "order": { "_count": "desc" },
        "missing": "UNKNOWN",
        "include": ["paid", "refunded"],
        "show_term_doc_count_error": true
      }
    }
  }
}

语义要点:

  • 默认 top N 是近似分布式排序 。每分片返回 shard_size 个候选;默认
    shard_size = size * 1.5 + 10。sum_other_doc_count 表示未进入响应的文档数。
  • doc_count_error_upper_bound 只在某些排序下可计算 。按 _count desc 排序
    时可给出误差上界;按 _key、子聚合或其他顺序时常见为 -1。
  • 不要用 _count asc 找稀有词 。每分片只返回局部 top N,全局低频值可能被
    完全丢掉;应使用 rare_terms。
  • 子聚合排序只有少数模式天然安全 :最大值降序、最小值升序、_key 升降序。
    最小值降序、最大值升序容易丢桶。pipeline 聚合不能参与 terms 排序。
  • include/exclude 支持正则、精确值和分片分区 。partition + num_partitions
    用于分批处理超大基数,但不能与 exclude 同用。
  • 跨索引字段类型要一致 。混合 decimal/non-decimal 时会提升类型,可能导致
    数值精度变化;unmapped 字段可用 value_type 帮助解析。
multi_terms

multi_terms 把多个字段值组合成一个复合键,最少 2 个、最多 128 个 key。

它比单字段 terms 更慢、更耗内存;字段组合固定且常用时,官方建议索引期生成

combined keyword 字段,再用普通 terms 聚合。

http 复制代码
{
  "aggs": {
    "region_status": {
      "multi_terms": {
        "terms": [
          { "field": "region" },
          { "field": "status" }
        ],
        "size": 20
      }
    }
  }
}

multi_terms 支持 terms 的大部分参数,文档说明 collect_mode 默认是

breadth_first。只要不是为了排序 top 组合,全量遍历优先 composite。

源码锚点:MultiTermsAggregationBuilder.java:42。

rare_terms

rare_terms 是为"低频词"设计的近似聚合,不是 terms + _count asc。

参数 max_doc_count 默认 1、最大 100;precision 默认 0.001,最小

0.00001。内部使用 CuckooFilter 快速跳过已确认超过阈值的常见词。

需要注意:CuckooFilter 的 false positive 会让一个实际仍低频的词被误判为常见词,

因此最终结果可能出现漏报 ,而不是把高频词返回成低频。分片各自只看到局部

计数,也更容易在分片层触发 search.max_buckets,协调节点合并后又会裁剪出更小

的真正低频集合。

源码锚点:RareTermsAggregationBuilder.java:32、:39。

significant_terms

significant_terms 比较 foreground(当前查询/父桶命中的文档)和

background(索引或自定义背景集合)的词频差异,适合异常检测、查询扩展、安全

调查。典型响应包含 doc_count、bg_count 和 score。

http 复制代码
{
  "query": { "term": { "force": "British Transport Police" } },
  "aggs": {
    "significant_crime_types": {
      "significant_terms": { "field": "crime_type" }
    }
  }
}

可用启发式包括 jlh、mutual_information、chi_square、gnd、percentage、

p_value,也可用 script_heuristic 自定义。默认 min_doc_count 是 3;

background_filter 可收窄背景集合,但会更慢。

限制:

  • 必须使用索引值,不支持脚本生成的 foreground/background 词;
  • 不支持 float 字段;
  • 不要在 match_all 上作为顶层聚合,此时 foreground 与 background 几乎相同;
  • 大子聚合放在它下面容易造成候选桶先生成再丢弃的浪费,可拆两段查询。

源码锚点:SignificantTermsAggregationBuilder.java:42。

significant_text

significant_text 专门处理 text 字段:它从 _source 重新分析文本,不需要

fielddata/doc values,因此能返回"原词形态"的关键词。代价是查询期 CPU 和内存

高,必须用 sampler 或 diversified_sampler 限制输入规模。

http 复制代码
{
  "query": { "match": { "content": "bird flu" } },
  "aggs": {
    "sample": {
      "sampler": { "shard_size": 200 },
      "aggs": {
        "keywords": {
          "significant_text": {
            "field": "content",
            "filter_duplicate_text": true
          }
        }
      }
    }
  }
}

它不支持子聚合,也不支持 nested 对象中的 text 字段。filter_duplicate_text

会过滤连续 6 个以上重复 token,减少转载、页脚、模板文本造成的伪相关。

源码锚点:SignificantTextAggregationBuilder.java:35。

18.3 filter、filters、range 与作用域

filter

filter 是单桶聚合,把子聚合限制在布尔条件内。它不参与评分。

http 复制代码
{
  "aggs": {
    "paid": {
      "filter": { "term": { "status": "paid" } },
      "aggs": { "revenue": { "sum": { "field": "amount" } } }
    }
  }
}
filters

filters 可声明多个命名或匿名桶。other_bucket: true 会生成"其他"桶;

匿名桶用数组返回,命名桶用对象返回。

http 复制代码
{
  "aggs": {
    "status_groups": {
      "filters": {
        "other_bucket": true,
        "filters": {
          "paid":   { "term": { "status": "paid" } },
          "failed": { "term": { "status": "failed" } }
        }
      }
    }
  }
}
range、date_range、ip_range

range 的桶边界语义是包含下界、不包含上界 ;keyed: true 返回对象而不是

数组。范围字段聚合要注意:range 值可能跨桶,文档会在多个桶中计数。

http 复制代码
{
  "aggs": {
    "price_ranges": {
      "range": {
        "field": "price",
        "keyed": true,
        "ranges": [
          { "to": 100 },
          { "from": 100, "to": 500, "key": "mid" },
          { "from": 500 }
        ]
      }
    }
  }
}

date_range 额外支持日期数学、format、time_zone:

http 复制代码
{
  "date_range": {
    "field": "created_at",
    "format": "yyyy-MM-dd",
    "ranges": [
      { "to": "now-7d/d", "key": "older" },
      { "from": "now-7d/d", "key": "recent" }
    ]
  }
}

ip_range 接受 CIDR 或起止地址:

http 复制代码
{
  "ip_range": {
    "field": "client_ip",
    "ranges": [
      { "to": "10.0.0.5" },
      { "from": "10.0.0.5", "to": "10.0.0.10" },
      { "mask": "10.0.0.0/25" }
    ]
  }
}
ip_prefix

ip_prefix 把 IP 按前缀长度分桶,适合 IPv4/IPv6 地址分布、子网聚合。

源码锚点:IpPrefixAggregationBuilder.java:40。

missing 与 global
  • missing 把缺少该字段的文档放入指定键。
  • global 忽略顶层 query,返回索引全局聚合;只有当父查询需要过滤主结果、
    同时又想展示全量统计时才使用。

18.4 直方图族

histogram

histogram 按固定数值步长分桶。官方给出的键计算公式:

text 复制代码
bucket_key = Math.floor((value - offset) / interval) * interval + offset

参数要点:

参数 语义
interval 正数,固定步长
offset [0, interval),平移桶边界
min_doc_count 默认 0,保留空桶
extended_bounds 扩展输出范围,不是过滤数据
hard_bounds 真正限制桶范围
keyed 返回按桶键索引的对象
missing 给缺值文档指定桶

extended_bounds 只影响"输出哪些桶",不改变文档归属。若查询已经限制

price <= 500,但某 range 字段跨桶,文档仍可能落在查询范围之外的桶。

对预聚合 histogram 字段执行 histogram 聚合时,结果只包含各区间的 counts,

不能有子聚合 ;missing 也不支持。

源码锚点:HistogramAggregationBuilder.java:41;

Histogram.java:19/24/25 分别定义 interval、extended_bounds、hard_bounds。

date_histogram

date_histogram 是时间序列聚合的基础。

http 复制代码
{
  "date_histogram": {
    "field": "@timestamp",
    "calendar_interval": "day",
    "time_zone": "Asia/Shanghai",
    "format": "yyyy-MM-dd",
    "min_doc_count": 0
  }
}

calendar_interval 只接受单数日历单位:minute/hour/day/week/month/quarter/year,

不允许 2d。fixed_interval 接受 SI 固定单位:ms/s/m/h/d,不允许周、月、季、

年这类自然日历单位。默认 UTC 分桶;time_zone 影响 UTC 与本地边界转换,

offset 在 time_zone 调整后生效。

DST、时区偏移和月份长度会让 calendar interval 的实际时长变化。报表系统应把

key_as_string 和 key 同时记录;不要用字符串格式二次解析回时间再排序。

源码锚点:DateHistogramAggregationBuilder.java:48;

DateIntervalWrapper.java:36-37 定义 fixed_interval 与 calendar_interval。

auto_date_histogram 与 variable_width_histogram

auto_date_histogram 只要求目标桶数 buckets,系统自动选择日历/固定 interval,

可配合 minimum_interval 避免过细。适合用户不知道合适粒度的报表。

variable_width_histogram 按数据分布生成宽度不等的数值桶,目标是每桶近似同样

数量的值。桶边界不像 fixed histogram 那样可直接预测;它不适合作为固定的业务

分档规则。

源码锚点:AutoDateHistogramAggregationBuilder.java:42;

VariableWidthHistogramAggregationBuilder.java:36。

18.5 composite:游标式遍历

composite 是唯一面向"高效分页遍历所有复合桶"的多桶聚合。它和 scroll 不同:

遍历的是桶键,不是文档。响应返回 after_key,下一页把它放回 after。

http 复制代码
POST sales/_search
{
  "size": 0,
  "aggs": {
    "buckets": {
      "composite": {
        "size": 100,
        "sources": [
          {
            "day": {
              "date_histogram": {
                "field": "created_at",
                "calendar_interval": "day"
              }
            }
          },
          { "region": { "terms": { "field": "region" } } }
        ]
      },
      "aggs": { "revenue": { "sum": { "field": "amount" } } }
    }
  }
}

要点:

  1. sources 顺序就是 key 排序顺序 。可以是 terms、histogram、
    date_histogram、geotile_grid。
  2. 默认 size 是 10,批量遍历建议 100~1000,不要一次取几万桶。
  3. 永远使用响应 after_key。不要从最后一个 bucket 自行推导 key。
  4. 缺失值默认丢弃 。missing_bucket: true 可生成 null 桶,
    missing_order 控制 first/last/default。
  5. 不能与 pipeline 聚合兼容 。一页只是全序列的一段,derivative 或
    cumulative_sum 在页内计算没有全局意义。
  6. 索引排序可提前终止 。source 前缀应匹配 index.sort.field 和
    index.sort.order;官方建议 track_total_hits: false。
  7. 它是昂贵聚合。官方文档首段就警告生产环境必须压测。

源码锚点:CompositeAggregationBuilder.java:40、:43-44;

CompositeAggregator.java:115 读取 max bucket 设置。

18.6 地理聚合

地理网格
聚合 key 形态 典型用途
geohash_grid geohash 字符串 兼容旧地图/存储
geotile_grid zoom/x/y Web 地图 tile
geohex_grid H3 cell index 六边形地图与空间分析

geohex_grid 的 precision 范围是 0~15,默认 6;size 默认 10,000;

shard_size 默认为 max(10, size * number-of-shards),用于提高最终 top cell

计数准确性。高 precision 会生成海量 cell,必须先 geo_bounding_box 查询,

或用聚合自带 bounds 限制 cell。

http 复制代码
{
  "aggs": {
    "city_zoom": {
      "filter": {
        "geo_bounding_box": {
          "location": {
            "top_left": "POINT (4.9 52.4)",
            "bottom_right": "POINT (5.0 52.3)"
          }
        }
      },
      "aggs": {
        "hex": {
          "geohex_grid": { "field": "location", "precision": 12 }
        }
      }
    }
  }
}

geo_shape 会因形状跨 tile/hex 而在多个桶中计数;低纬度、低 precision 下

投影语义差异更明显。

源码锚点:GeoGridAggregationBuilder.java:39-40 定义 size/shard_size。

geo_distance

geo_distance 以一个点为圆心,按距离区间分桶:

http 复制代码
{
  "aggs": {
    "around_office": {
      "geo_distance": {
        "field": "location",
        "origin": "52.3760, 4.8940",
        "ranges": [
          { "to": 1000 },
          { "from": 1000, "to": 5000 },
          { "from": 5000 }
        ],
        "unit": "m"
      }
    }
  }
}

源码锚点:GeoDistanceAggregationBuilder.java:46。

18.7 文档关系聚合

nested / reverse_nested

nested 将聚合上下文切到 nested 对象。子聚合统计的是子文档,不是父文档。

要回到父文档或另一个 unrelated nested 上下文,用 reverse_nested。

http 复制代码
{
  "aggs": {
    "resellers": {
      "nested": { "path": "resellers" },
      "aggs": {
        "min_price": { "min": { "field": "resellers.price" } },
        "root_avg_stock": {
          "reverse_nested": {},
          "aggs": { "avg_stock": { "avg": { "field": "stock" } } }
        }
      }
    }
  }
}

源码锚点:

text 复制代码
server/.../bucket/nested/NestedAggregationBuilder.java:29
server/.../bucket/nested/ReverseNestedAggregationBuilder.java:30
children / parent

这两个聚合作用于 join 字段的父子关系,位于 parent-join 模块。

children 进入指定子类型文档上下文;parent 进入父类型文档上下文。

它们与 nested 不同:nested 是同一文档内部的隐藏子文档,join 是显式父/子文档。

源码锚点:

text 复制代码
modules/parent-join/.../ChildrenAggregationBuilder.java:36
modules/parent-join/.../ParentAggregationBuilder.java:37

18.8 采样与关联

sampler

sampler 按相关性保留每分片 top shard_size 个匹配文档,不是随机采样。

它适合在 significant_text、top hits 分析前降低输入规模。因为依赖 score,

不能嵌套在会丢弃 score 的 breadth_first terms 下面。

http 复制代码
{
  "aggs": {
    "sample": {
      "sampler": { "shard_size": 200 },
      "aggs": {
        "keywords": { "significant_text": { "field": "content" } }
      }
    }
  }
}

源码锚点:SamplerAggregationBuilder.java:29;

SamplerAggregator.java:45/47 定义 shard_size 与 execution_hint。

diversified_sampler

diversified_sampler 在采样时按字段值去重,避免同一用户、同一 host、同一

session 占满样本。field 可以是 keyword/numeric,max_docs_per_value 控制

每个键最多保留多少文档。

源码锚点:DiversifiedAggregationBuilder.java:33。

random_sampler

random_sampler 是技术预览功能。它对分片背景文档集 随机采样;如果请求有

query,query 在采样后应用,而不是先查再随机抽。参数 probability 必须大于 0、

小于 0.5 或正好等于 1;seed 固定后,在同一个未变化分片上重复结果一致,

但 segment merge、删除、新增会改变被采到的具体文档。

除 cardinality 外,普通计数会被按概率缩放。例如 probability: 0.1 且桶

doc_count: 10000 表示实际约 1000 个文档。唯一值数量不适合自动缩放。

源码锚点:RandomSamplerAggregationBuilder.java:31。

adjacency_matrix

adjacency_matrix 对多个 filter 的交集建模,能输出 A & B、A & B & C 这类

组合桶,适合安全事件共现、标签交叉分析。

源码锚点:modules/aggregations/.../AdjacencyMatrixAggregationBuilder.java:39。

18.9 x-pack 桶聚合

categorize_text

categorize_text 把机器生成的半结构化文本按格式归类,适合日志模板发现。

它重新分析 field 文本并只用前 100 个 token 参与归类;similarity_threshold

默认 70,取值 1~100,值越大类别越窄、内存越高。

http 复制代码
{
  "aggs": {
    "log_patterns": {
      "categorize_text": {
        "field": "message",
        "categorization_filters": ["\\w+_\\d{3}"],
        "size": 20
      }
    }
  }
}

categorization_filters 与 categorization_analyzer 不能同时使用。前者是简单

正则过滤;后者可完整配置 char filter、tokenizer 和 filter。大结果集应配合

Async search 和采样。

源码锚点:

x-pack/plugin/ml/.../CategorizeTextAggregationBuilder.java:37。

time_series

time_series 作用于 TSDS 索引,按时间序列生成桶。9.7+ 官方文档已明确将其

标记为 deprecated,并推荐 ES|QL TS 命令。它限制多、会关闭大量聚合优化,

与 composite、global、top_hits、rare_terms、auto_date_histogram 和

sampler 组合容易异常。旧监控代码应迁移到 ES|QL。

源码锚点:

modules/aggregations/.../TimeSeriesAggregationBuilder.java:34。

frequent_item_sets

frequent_item_sets 用于发现频繁项集,适合事务/告警特征组合分析。源码保留

旧名 frequent_items 作为 deprecated name:

text 复制代码
FrequentItemSetsAggregationBuilder.java:41   // NAME = frequent_item_sets
FrequentItemSetsAggregationBuilder.java:44   // DEPRECATED_NAME = frequent_items

第 19 章 指标聚合与管道聚合(metrics/pipeline)

出处:refs/official-docs/reference/aggregations/metrics.md、pipeline.md 及各子页

源码:server/.../search/aggregations/metrics/、

server/.../search/aggregations/pipeline/、

x-pack/plugin/analytics/、modules/aggregations/

19.1 指标聚合总表

metric 聚合不划分文档;它在当前文档集合上输出统计值。官方 TOC 中的

metric/pipeline 相关条目按用途可分成下表。括号内是响应中常见的输出。

聚合 输入/输出 用途
avg 数值字段,单值 平均值;缺值默认跳过,missing 可指定
sum 数值字段,单值 求和
min / max 数值/date/ip 可比较值,单值 最小/最大值
stats 数值字段 count、min、max、avg、sum
extended_stats 数值字段 stats + sum_of_squares、variance、std_deviation 等样本/总体口径
value_count 字段值 计算值数量,不是文档数
weighted_avg value + weight 加权平均,weight 必须非空
cardinality 字段/脚本值 HLL++ 近似唯一值数量
percentiles 数值或 histogram 字段 近似分位数
percentile_ranks 数值 + values 求给定值的百分位排名
median_absolute_deviation 数值字段 中位绝对偏差,内部 TDigest
string_stats keyword/text 字段 字符串长度统计与 entropy
top_hits bucket 内命中文档 返回 top docs,用于桶内样本
top_metrics 排序后的 top docs 取每个 top doc 的一个或多个 metric
scripted_metric init/map/combine/reduce 自定义聚合,代价最高
geo_bounds geo_point/geo_shape 地理边界框
geo_centroid geo_point/geo_shape 地理质心
geo_line geo_point 聚合轨迹线,x-pack analytics
cartesian_bounds cartesian_point/shape 平面边界框
cartesian_centroid cartesian_point/shape 平面质心
boxplot 数值/histogram min/max/q1/q2/q3,x-pack analytics
t_test 两组数值字段 配对/非配对/异方差 t 检验
matrix_stats 多个数值字段 多字段相关矩阵
rate date_histogram/composite 上下文 文档数或字段值速率
roaring_bitmap 文档集 压缩位图集合,内部场景常用

普通单值/多值 metric 的位置由父聚合决定。在顶层是"全查询"的统计;在

terms 桶下是"每个 term 的统计"。top_hits 是桶分析里最有用的样本工具:

http 复制代码
{
  "size": 0,
  "aggs": {
    "by_region": {
      "terms": { "field": "region", "size": 5 },
      "aggs": {
        "recent_samples": {
          "top_hits": {
            "size": 3,
            "sort": [{ "created_at": "desc" }],
            "_source": ["order_id", "amount", "created_at"]
          }
        }
      }
    }
  }
}

top_hits 不要当作导出全量结果的分页机制;它属于"桶内代表性文档"。

top_metrics 更轻,适合只取 top 文档的字段值:

http 复制代码
{
  "aggs": {
    "best_products": {
      "terms": { "field": "category" },
      "aggs": {
        "max_sales": {
          "top_metrics": {
            "metrics": { "field": "sales" },
            "sort": { "sales": "desc" }
          }
        }
      }
    }
  }
}

源码锚点:TopMetricsAggregationBuilder.java:42。

19.2 近似算法:HLL++、TDigest 与 HDR

cardinality:HyperLogLog++

cardinality 计算 distinct 值数量,但不是精确 set。官方文档说明它基于

HyperLogLog++:通过哈希值前导零估计基数,内存随精度阈值可预估,

而不是随数据量线性增长。

http 复制代码
{
  "aggs": {
    "unique_users": {
      "cardinality": {
        "field": "user_id",
        "precision_threshold": 3000
      }
    }
  }
}
参数/行为 值
precision_threshold 默认 3000
最大有效值 40000,更大等效 40000
内存估算 约 c * 8 字节
execution_hint 默认 save_time_heuristic

对超大高基数字符串字段,可考虑 mapper-murmur3 预计算 hash;这主要是

CPU/内存换磁盘空间。不要对低基数数值字段做这种优化。

percentiles:TDigest、HDR 和 nondeterminism

percentiles 默认用 TDigest。它不是精确排序集合,而是分位数草图。官方要点:

  1. 小数据集可能非常精确,大数据集用内存换误差。
  2. 误差分布与 q(1-q) 有关,极端分位数通常比中位数更精确。
  3. 相同数据可能出现轻微不同结果,因为它本质上是非确定算法。
  4. compression 默认 100,越大越准、越慢;节点数量上限约为
    20 * compression。
  5. execution_hint: high_accuracy 可提高精度,但官方文档提示可能 2~10 倍变慢。
http 复制代码
{
  "aggs": {
    "latency_p": {
      "percentiles": {
        "field": "latency_ms",
        "percents": [50, 95, 99, 99.9],
        "tdigest": { "compression": 200 }
      }
    }
  }
}

HDR Histogram 是另一个实现,适合延迟类数据;number_of_significant_value_digits

控制分辨率。它只支持正值;值域未知时可能占用大量内存。

http 复制代码
{
  "percentiles": {
    "field": "latency_ms",
    "percents": [95, 99],
    "hdr": { "number_of_significant_value_digits": 3 }
  }
}

percentile_ranks 是反向查询:给定一组值,返回其对应百分位。它的输入不是

分位数数组,而是 values 数组。它同样依赖近似草图。

19.3 管道聚合:buckets_path、gap policy 与执行位置

pipeline 聚合在普通聚合结果生成之后运行,因此它不能再拥有普通子聚合。

它只读取其他聚合输出的桶/指标。

buckets_path 语法
路径 含义
sales 同层 metric 聚合 sales
sales_per_month>sales 从兄弟多桶聚合 sales_per_month 下的 sales
a>b.avg 进入子桶 a,再取 b 的 avg
_count 使用父桶文档数
categories._bucket_count 使用多桶聚合返回的桶数
my_percentile[99.9] 聚合名或 metric 名带点时用方括号

路径必须相对当前 pipeline 的位置,不能向上回溯。

gap policy
值 行为
skip 缺失桶不存在,pipeline 跳过该桶
insert_zeros 把缺失值替换为 0 后继续计算
keep_values 如果 metric 有非 null/non-NaN 值则保留,否则跳过空桶

"空桶"常见来源:某个时间桶没有文档;某个 metric 在桶里没有可计算值;

上层 metric 依赖的子桶缺失。做累计曲线时,min_doc_count 默认 0 并选择

合适 gap policy 比先补数据更重要。

父 pipeline 与兄弟 pipeline
类型 聚合 位置
parent derivative、cumulative_sum、cumulative_cardinality、moving_fn、moving_percentiles、bucket_script、bucket_selector、bucket_sort、normalize、serial_diff 放在多桶聚合的 aggs 里,作用于父多桶序列
sibling avg_bucket、max_bucket、min_bucket、sum_bucket、stats_bucket、extended_stats_bucket、percentiles_bucket 放在目标多桶聚合旁边,用 buckets_path 指向它
x-pack inference_bucket、bucket_correlation、bucket_count_ks_test 等 按各自文档定义放置

官方当前参考以 moving_fn 为准。不要在新代码里寻找独立 moving_avg

参数;Elasticsearch 早期版本的 moving average 已由 moving_fn 取代。

derivative 与 cumulative_sum
http 复制代码
POST sales/_search
{
  "size": 0,
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "month"
      },
      "aggs": {
        "sales": { "sum": { "field": "price" } },
        "sales_deriv": {
          "derivative": { "buckets_path": "sales" }
        },
        "cumulative_sales": {
          "cumulative_sum": { "buckets_path": "sales" }
        }
      }
    }
  }
}

derivative 第一桶没有前值,因此不输出值;第二桶是当前值 - 上一桶值。

cumulative_sum 是前缀和。源码锚点:

DerivativePipelineAggregationBuilder.java:34、

CumulativeSumPipelineAggregationBuilder.java:27。

moving_fn
http 复制代码
{
  "moving_fn": {
    "buckets_path": "sales",
    "window": 10,
    "shift": 0,
    "script": "MovingFunctions.unweightedAvg(values)"
  }
}

window 是滑动窗口大小;shift: 0 表示窗口不含当前桶,shift: 1 包含当前桶,

shift: window/2 可居中。内置函数在 MovingFunctions 命名空间下:

max、min、sum、stdDev、unweightedAvg、linearWeightedAvg、ewma、

holt、holtWinters。Holt-Winters 需要至少两个周期做冷启动。

源码锚点:MovFnPipelineAggregationBuilder.java:37;

server/.../pipeline/MovingFunctions.java。

bucket_script、bucket_selector、bucket_sort

bucket_script 在每个桶上计算表达式:

http 复制代码
{
  "conversion": {
    "bucket_script": {
      "buckets_path": {
        "orders": "orders_count",
        "visits": "visit_count"
      },
      "script": "params.orders / params.visits * 100"
    }
  }
}

bucket_selector 用布尔表达式保留或丢弃桶。它发生在普通聚合之后,

不能降低已经执行的聚合成本,只能减少响应中的桶。

http 复制代码
{
  "big_regions": {
    "bucket_selector": {
      "buckets_path": { "revenue": "revenue" },
      "script": "params.revenue > 10000"
    }
  }
}

bucket_sort 对父多桶聚合的桶排序,并可用 from/size 截断:

http 复制代码
{
  "revenue_top10": {
    "bucket_sort": {
      "sort": [{ "revenue": "desc" }],
      "from": 0,
      "size": 10
    }
  }
}
normalize

normalize 把父序列重缩放为可比较尺度。可用方法:

方法 效果
rescale_0_1 min=0,max=1
rescale_0_100 min=0,max=100
percent_of_sum 每个值除以总和
mean 相对均值的线性缩放
z-score 相对均值和标准差
softmax 指数归一化

源码锚点:

x-pack/plugin/analytics/.../NormalizePipelineAggregationBuilder.java:38。

sibling pipeline

avg_bucket/max_bucket/min_bucket/sum_bucket 是四件套,通常放在目标多桶聚合

旁边:

http 复制代码
{
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "month"
      },
      "aggs": {
        "sales": { "sum": { "field": "price" } }
      }
    },
    "max_monthly_sales": {
      "max_bucket": { "buckets_path": "sales_per_month>sales" }
    }
  }
}

stats_bucket、extended_stats_bucket、percentiles_bucket 对整条序列做统计。

19.4 x-pack 与矩阵类指标

boxplot

boxplot 输出 min、q1、q2、q3、max,适合异常值概览。它也基于 TDigest 类

草图,compression 越大越准。

源码锚点:x-pack/plugin/analytics/.../BoxplotAggregationBuilder.java:36。

t_test

t_test 支持三种检验:

type 说明
paired 同一对象前后对比
homoscedastic 独立两组,方差假设相同
heteroscedastic 独立两组,不假设方差相同

源码锚点:x-pack/plugin/analytics/.../TTestAggregationBuilder.java:38。

matrix_stats

matrix_stats 接收多个数值字段,输出字段级统计、协方差、相关性矩阵。

它不是桶聚合;想按组分析相关矩阵,应先套桶聚合。

http 复制代码
{
  "aggs": {
    "matrix": {
      "matrix_stats": { "fields": ["age", "income", "tenure"] }
    }
  }
}

源码锚点:MatrixStatsAggregationBuilder.java:27。

rate

rate 必须位于 date_histogram 中;若位于 composite 中,则 composite 必须有

且只有一个 date_histogram source。它计算文档速率或字段值速率。

http 复制代码
{
  "date_histogram": {
    "field": "@timestamp",
    "calendar_interval": "month"
  },
  "aggs": {
    "daily_revenue": {
      "rate": { "field": "revenue", "unit": "day" }
    }
  }
}

unit 支持日历单位。不是所有组合都兼容:例如 month 粒度可直接换算成

month/quarter/year,day 粒度可换算成 day/hour/week 等同组单位。

mode: sum 是默认,mode: value_count 改为统计值个数。

源码锚点:

x-pack/plugin/analytics/.../RateAggregationBuilder.java:32。

19.5 选型速查

场景 推荐
精确平均值/总和/最大值 avg、sum、max
唯一用户数 cardinality + 合适 precision_threshold
P95/P99 延迟 percentiles TDigest;极高精度要求用 high_accuracy 或 HDR
桶内看样本文档 top_hits
桶内 top 值 top_metrics
同一对象的 A/B 前后对比 t_test paired
多字段关系 matrix_stats
月度累计销售额 date_histogram + sum + cumulative_sum
周环比/月环比 derivative 或 serial_diff
转化率 桶内 metric + bucket_script
只展示超过阈值的桶 bucket_selector,但不要当作性能优化
可视化地图 geo grid + geo_centroid/geo_bounds

第 20 章 文本分析(text analysis)全栈

出处:refs/official-docs/reference/text-analysis/index.md、analyzer-reference.md、

tokenizer-reference.md、token-filter-reference.md、character-filter-reference.md、

normalizers.md;refs/docs-content/manage-data/data-store/text-analysis/

源码:server/src/main/java/org/elasticsearch/index/analysis/、

modules/analysis-common/、indices/analysis/AnalysisModule.java

文本分析把 "Quick foxes jumped" 变成可倒排的 token 流。它决定 match 能否命中、

短语能否相邻、高亮能否定位。错误的分析链路通常不是"查询语法错误",而是

索引期和查询期生成了两套不同的词。

20.1 分析链路与索引/搜索期

一个 analyzer 由三段组成:

text 复制代码
原始文本
  → character filter(s)   增删改字符流
  → tokenizer             必须恰好一个;切 token,记录 position/offset/type
  → token filter(s)       0 个或多个;改写、删除、增加 token
  → Lucene token stream

规则有三条:

  1. character filter 可以有零个或多个,按声明顺序执行;
  2. tokenizer 必须恰好一个;
  3. token filter 可以有零个或多个,但不能改变 token 的 position 和
    character offset
    。官方 anatomy 文档明确写了这条限制。

源码入口:

text 复制代码
indices/analysis/AnalysisModule.java:55        // 模块装配
AnalysisModule.java:74-84                      // char_filter/token_filter/tokenizer/analyzer/normalizer 注册
index/analysis/AnalysisRegistry.java:60        // per-node registry
AnalysisRegistry.java:287                      // getAnalyzer()
AnalysisRegistry.java:432                      // build(IndexCreationContext, IndexSettings)
AnalysisRegistry.java:436-437                  // 构建 analyzer 与 normalizer factories

分析在两个时点发生:

  • index time :写入 text 字段时分析文档值;
  • search time :对 match、match_phrase 等全文查询分析查询串。

索引期 analyzer 的选择顺序是:字段 analyzer →

index.analysis.analyzer.default → standard。

搜索期顺序是:查询里的 analyzer → 字段 search_analyzer →

index.analysis.analyzer.default_search → 字段 analyzer → standard。

出处:refs/docs-content/manage-data/data-store/text-analysis/specify-an-analyzer.md。

大多数场景应让索引期和搜索期使用同一个 analyzer。只有前缀检索、缩写输入、

大写品牌词这类"原始值和查询值本来就应该走不同形态"的场景,才显式拆分。

20.2 内置 analyzer

官方 analyzer-reference.md 列出 8 类内置 analyzer;language 不是单一类型,

而是一组语言专用 analyzer。不要因为大纲写"9 种"就把 language 拆成第 9 个

同名 type。

type 定义
standard 默认 analyzer;Unicode Text Segmentation 切词、移除多数标点、lowercase,stop filter 默认关闭
simple 非字母即分隔,输出 lowercase
whitespace 只按空白切分,不 lowercase
stop simple + 停用词过滤
keyword no-op analyzer,整段输出为一个 term
pattern 正则切分,支持 lowercase 与停用词
language 36 个语言类型,如 english、french、cjk、thai
fingerprint lowercase、ASCII folding、排序、去重、拼接成单 token

standard 默认 max_token_length: 255;可配置 stopwords 或

stopwords_path。下面示例来自官方文档:

http 复制代码
POST _analyze
{
  "analyzer": "standard",
  "text": "The 2 QUICK Brown-Foxes jumped over the lazy dog's bone."
}

输出为:

text 复制代码
[ the, 2, quick, brown, foxes, jumped, over, the, lazy, dog's, bone ]

语言 analyzer 的关键不是"能不能分词",而是是否包含正确的小写规则、数字转换、

停用词、normalization 和 stemmer。english analyzer 的组成包括 possessive stemmer、

lowercase、English stop words、keyword marker(可选)和 English stemmer。

20.3 15 个内置 tokenizer

分类 tokenizer
词级 standard、letter、lowercase、whitespace、uax_url_email、classic、thai
局部词 ngram、edge_ngram
结构化文本 keyword、pattern、simple_pattern、char_group、simple_pattern_split、path_hierarchy

语义速览:

tokenizer 典型行为
standard Unicode 文本分段,适合大多数自然语言
letter 非字母即分隔
lowercase letter 切分 + lowercase
whitespace 只按空白切分,保留大小写和标点
uax_url_email 类似 standard,但把 URL/email 当成单个 token
classic 英语语法式切分
thai 泰文专用分词
ngram 滑动窗口切出任意连续片段
edge_ngram 从词首锚定的前缀片段
keyword 整段一个 token
pattern 正则做分隔或捕获
simple_pattern 受限正则捕获,比 pattern 快
simple_pattern_split 受限正则按匹配位置切分
char_group 指定字符集合切分,便宜且可预测
path_hierarchy /a/b/c 输出 /a、/a/b、/a/b/c

ngram/edge_ngram 是查询体验和索引体积/写入速度的直接交换。不要在未收窄

min_gram/max_gram/token_chars 时对长文本开 ngram;先考虑 search_as_you_type

或 edge ngram 只做索引期前缀。

20.4 token filter 大全

官方 token-filter-reference.md 当前有 48 个参考页。其中 "Normalization"

是一个说明页,内部包含多个语言 normalization filter,所以"48 个页面"不等于

"48 个可配置 type"。按用途分组如下:

用途 filter
大小写 lowercase、uppercase、trim
字符规范化 asciifolding、decimal_digit、cjk_width、Normalization 族
停用词与白名单 stop、keep_words、keep_types
词干化 stemmer、porter_stem、kstem、snowball、hunspell、stemmer_override、keyword_marker
复合词 dictionary_decompounder、hyphenation_decompounder
连接词与变体 apostrophe、elision、common_grams、classic
同义词与图 synonym、synonym_graph、flatten_graph
部分匹配 ngram、edge_ngram、shingle
结构拆分 word_delimiter、word_delimiter_graph、pattern_capture
去重与重复 keyword_repeat、remove_duplicates、unique
流控制 length、limit_token_count、condition、predicate_token_filter、multiplexer
载荷与指纹 delimited_payload、fingerprint、minhash
语音匹配 phonetic
其他 pattern_replace、reverse、truncate、cjk_bigram

注意两条边界:

  • token filter 不改 position/offset 。需要改变文本位置语义的工作交给
    tokenizer 或 char filter。
  • graph filter 是特例 。synonym_graph、word_delimiter_graph、
    flatten_graph 会构造多位置 token 图,服务短语和邻近查询;但索引期和搜索期
    都要小心位置膨胀。

同义词示例:

http 复制代码
PUT products
{
  "settings": {
    "analysis": {
      "filter": {
        "product_synonyms": {
          "type": "synonym_graph",
          "synonyms": [
            "notebook, laptop",
            "mobile phone => smartphone"
          ]
        }
      },
      "analyzer": {
        "product_search": {
          "tokenizer": "standard",
          "filter": ["lowercase", "product_synonyms"]
        }
      }
    }
  }
}

同义词建议只放搜索期,除非有明确理由让文档 token 流也扩展。索引期同义词会

增加倒排项,且难以随业务词表热更新。

20.5 3 个 character filter

官方只有 3 个内置 character filter:

type 作用
html_strip 去掉 HTML 元素并解码 HTML entity
mapping 按映射表替换字符串
pattern_replace 按正则替换字符串
http 复制代码
PUT web_pages
{
  "settings": {
    "analysis": {
      "char_filter": {
        "clean_html": { "type": "html_strip" },
        "brands": {
          "type": "mapping",
          "mappings": ["MySQL => mysql", "PostgreSQL => postgres"]
        }
      },
      "analyzer": {
        "page": {
          "char_filter": ["clean_html", "brands"],
          "tokenizer": "standard",
          "filter": ["lowercase"]
        }
      }
    }
  }
}

char filter 的偏移语义很关键:html_strip 会改变原始字符串长度,因此必须保持

token offset 指向过滤后字符流中的正确位置,否则高亮会错位。源码锚点:

20.6 normalizer

normalizer 是 keyword 字段的轻量分析器:只允许产生一个 token,因此没有

tokenizer,只能使用部分 character filter 和 token filter。

内置 normalizer 是 lowercase。

官方允许的 filter 包括:

text 复制代码
arabic_normalization, asciifolding, bengali_normalization, cjk_width,
decimal_digit, elision, german_normalization, hindi_normalization,
indic_normalization, lowercase, pattern_replace, persian_normalization,
scandinavian_folding, serbian_normalization, sorani_normalization, trim, uppercase
http 复制代码
PUT tags
{
  "settings": {
    "analysis": {
      "normalizer": {
        "tag_normalizer": {
          "type": "custom",
          "filter": ["lowercase", "asciifolding", "trim"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "tag": { "type": "keyword", "normalizer": "tag_normalizer" }
    }
  }
}

它和 text + lowercase 的区别:keyword + normalizer 仍是一个 term,不参与 BM25

分词;适合精确值归一。keyword 字段源码中 normalizer 参数和加载路径:

text 复制代码
index/mapper/KeywordFieldMapper.java:140       // mapper 类
KeywordFieldMapper.java:269                    // normalizer 参数
KeywordFieldMapper.java:503-520                // 从 IndexAnalyzers 加载 normalizer
index/analysis/CustomNormalizerProvider.java:24
index/analysis/LowercaseNormalizerProvider.java
AnalysisRegistry.java:495-496                  // normalizer 只允许 NormalizingTokenFilterFactory

20.7 _analyze 与 explain 模式

_analyze 是分析链路的单元测试工具。全局可用:

http 复制代码
POST _analyze
{
  "analyzer": "standard",
  "text": "The quick brown fox."
}

也可以指定索引和字段,让 ES 使用映射中的索引/搜索 analyzer:

http 复制代码
GET my-index/_analyze
{
  "field": "content",
  "text": "The quick brown fox."
}

不用命名 analyzer 时,可以在请求里临时组合:

http 复制代码
POST _analyze
{
  "tokenizer": "standard",
  "char_filter": ["html_strip"],
  "filter": ["lowercase", "asciifolding"],
  "text": "Is this <b>déjà vu</b>?"
}

返回的每个 token 至少包含 token、start_offset、end_offset、type 和

position。高亮、短语查询和 span 查询都依赖这些元数据。

explain: true 返回每个分析阶段的 detail,可用于判断问题出在 char filter、

tokenizer 还是某个 token filter;attributes 可选择需要展示的 token attributes。

排障时建议固定三步:

  1. 先用文档中的原文片段跑 _analyze;
  2. 再用用户输入的查询串跑同一个 analyzer;
  3. 对比 token 序列、position、offset,而不是只看最终是否命中。

20.8 自定义 analyzer 实战

完整定义分两层:analysis.* 定义组件和 analyzer,mapping 把 analyzer 绑到字段。

http 复制代码
PUT content_index
{
  "settings": {
    "analysis": {
      "char_filter": {
        "strip_html": { "type": "html_strip" }
      },
      "filter": {
        "english_stop": {
          "type": "stop",
          "stopwords": "_english_"
        },
        "english_stem": {
          "type": "stemmer",
          "language": "english"
        }
      },
      "analyzer": {
        "content_index": {
          "type": "custom",
          "char_filter": ["strip_html"],
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "english_stop",
            "english_stem"
          ]
        },
        "content_search": {
          "type": "custom",
          "char_filter": ["strip_html"],
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "english_stop",
            "english_stem"
          ]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "content_index",
        "search_analyzer": "content_search",
        "fields": {
          "raw": { "type": "keyword" }
        }
      }
    }
  }
}

实践顺序:

  1. 先测试组件,再绑定字段 。用 _analyze 验证 token,不要只靠真实查询猜。
  2. text 与 keyword 并存 。排序、聚合用 keyword 子字段,全文检索用 text。
  3. stemming 与精确展示分离 。索引 stemming token,展示仍用 _source 原文。
  4. stop words 谨慎。停用词有时承载查询语义("not""to""between")。
  5. 同义词放搜索期。词表变化频繁时不要把业务词表烧进倒排索引。
  6. ngram 只用于短字段或受限前缀。全字段 ngram 通常制造索引灾难。
  7. 已有索引不能随便改 analyzer 。官方说明:给已有索引添加 analyzer 需要关闭
    索引、更新设置、再打开;data stream 的写入索引要改模板后 rollover,
    已有 backing index 若必须改 analyzer 通常要重建/reindex。

源码锚点:index/analysis/CustomAnalyzerProvider.java:26。

20.9 分析与高亮

高亮不是重新打分,而是把 query 的词项映射回原文片段。映射的基础是分析链路

记录的 offset。官方给出三种 offset 来源:

来源 mapping 设置 特点
postings offsets index_options: "offsets" unified highlighter 可直接读取,不用重分析,磁盘小于 term vector
term vectors term_vector: "with_positions_offsets" fvh 必需;大字段、多 term 查询快,但索引体积大
plain re-analysis 无 offsets/term vectors 每个字段、每个文档重新分析;大文本慢,默认限制 1,000,000 字符

unified 是 text/keyword 的默认高亮器,支持 BM25 passage scoring 和准确短语、

fuzzy、prefix、regex 高亮;plain 每次为字段/文档构建小型内存索引;

fvh 需要 term vectors,不支持 span query;semantic 用于

semantic/semantic_text 字段。

高亮排障:

现象 原因
查询命中但高亮缺词 query 与字段 analyzer 不一致;高亮使用了不同 analyzer
高亮位置错乱 char filter/自定义 filter 破坏 offset;自定义 analyzer 违反位置约束
大文档高亮慢 plain re-analysis;改用 postings offsets 或 term vectors
短语没按预期高亮 boolean/minimum_should_match 逻辑不总反映在高亮词项提取中
fvh 报错 字段没有 term_vector: with_positions_offsets

官方文档也提醒:highlighter 不完全反映复杂 boolean 逻辑,某些复杂查询会高亮

与最终匹配条件不完全对应的片段。


系列导航

  • Elasticsearch 9.x 从入门到精通(1/7):初识 Elasticsearch(第 01~04 章)
  • Elasticsearch 9.x 从入门到精通(2/7):数据建模与索引管理(第 05~08 章)
  • Elasticsearch 9.x 从入门到精通(3/7):检索与查询(第 09~16 章)
  • Elasticsearch 9.x 从入门到精通(4/7):聚合分析与文本分析(第 17~20 章)(本篇)
  • Elasticsearch 9.x 从入门到精通(5/7):集群、分布式与运维(第 21~26 章)
  • Elasticsearch 9.x 从入门到精通(6/7):生态与扩展(第 27~30 章)
  • Elasticsearch 9.x 从入门到精通(7/7):源码内幕与贡献(第 31~33 章)
相关推荐
数字新视界10 小时前
信创动环监控在机房环境管理中的智能化应用与实践分析
大数据·人工智能·物联网·信息与通信·动环监控系统
大大大大晴天15 小时前
数仓分层架构设计:ODS、DWD、DWS、ADS、DIM 如何各司其职
大数据
东鸿电子Eastron1 天前
工厂节能降本落地指南:从精准能源计量搭建数字化管理基础
大数据·人工智能·能源·智能电表·能耗管理
吾AI科技1 天前
基于Tez引擎的 Hive SQL 性能优化 —— 为什么脚本运行越来越慢
大数据·hive·性能优化·tez
P1Browser2 天前
账号触发平台安全审核?拆解标准申诉流程与材料清单
大数据·人工智能·安全·多账号管理·指纹浏览器·账户安全·运营合规
云南新人和数采集团2 天前
云南靠谱软件开发公司选型指南:以昆明新腾科技为例
大数据·人工智能·科技
AllData公司负责人2 天前
AI大模型数据开发底座系列说明书:AllData集成DB-GPT开源项目建设 AI 多模态分析底座,涵盖模态解析/智能大屏/MCP 扩展!
大数据·数据库·人工智能·gpt·数据采集·数据接入·模态解析
Elasticsearch2 天前
过犹不及:为什么搜索结果重排序时,20 个候选结果胜过 200 个
elasticsearch
wno7042 天前
常用的Git命令清单
大数据·git·elasticsearch