系列文章 :《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 的缩写。聚合树规则如下:
- 同名作用域唯一 :同一父聚合下,聚合名不能重复;不同分支可以重名,
但响应路径不同,不建议这样写。 - 只有桶聚合能带子聚合 :metric 聚合输出统计值,pipeline 聚合输出
后处理结果;两者不能继续嵌套子聚合。 - pipeline 无子聚合,但可引用 pipeline :
pipeline.md明确指出 pipeline
不接受子聚合,不过buckets_path可以引用另一个 pipeline,从而形成
二阶导数这类链式计算。 - 路径是相对路径 :
buckets_path从当前 pipeline 所在位置出发,不能向上
回溯。a>b.avg表示进入子桶聚合a,再取多值 metricb.avg。 - 嵌套文档先切上下文 :
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 性能与排障
按优先级处理聚合性能:
- 先查询,后聚合 :能用时间范围、term/range 过滤收窄数据集的,不要用
聚合分支假装过滤。 - 选对字段 :聚合/排序字段应有 doc values;
keyword子字段优先于开启
fielddata的text字段。 - 控制候选桶 :先估计基数,再设置
size、shard_size、min_doc_count;
全量遍历用composite分页。 - 观察近似信号 :
sum_other_doc_count、doc_count_error_upper_bound
非零时不要把结果当精确值。 - 警惕 runtime 字段:能索引成 keyword/numeric 就不要每次查询跑脚本。
- 限制深度 :聚合树不是树状数据库。过深嵌套会让查询计划难以推理,
源码也在构建阶段防御过深树(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" } } }
}
}
}
要点:
- sources 顺序就是 key 排序顺序 。可以是
terms、histogram、
date_histogram、geotile_grid。 - 默认 size 是 10,批量遍历建议 100~1000,不要一次取几万桶。
- 永远使用响应
after_key。不要从最后一个 bucket 自行推导 key。 - 缺失值默认丢弃 。
missing_bucket: true可生成 null 桶,
missing_order控制 first/last/default。 - 不能与 pipeline 聚合兼容 。一页只是全序列的一段,
derivative或
cumulative_sum在页内计算没有全局意义。 - 索引排序可提前终止 。source 前缀应匹配
index.sort.field和
index.sort.order;官方建议track_total_hits: false。 - 它是昂贵聚合。官方文档首段就警告生产环境必须压测。
源码锚点: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。它不是精确排序集合,而是分位数草图。官方要点:
- 小数据集可能非常精确,大数据集用内存换误差。
- 误差分布与
q(1-q)有关,极端分位数通常比中位数更精确。 - 相同数据可能出现轻微不同结果,因为它本质上是非确定算法。
compression默认 100,越大越准、越慢;节点数量上限约为
20 * compression。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
规则有三条:
- character filter 可以有零个或多个,按声明顺序执行;
- tokenizer 必须恰好一个;
- 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。
排障时建议固定三步:
- 先用文档中的原文片段跑
_analyze; - 再用用户输入的查询串跑同一个 analyzer;
- 对比 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" }
}
}
}
}
}
实践顺序:
- 先测试组件,再绑定字段 。用
_analyze验证 token,不要只靠真实查询猜。 - text 与 keyword 并存 。排序、聚合用
keyword子字段,全文检索用 text。 - stemming 与精确展示分离 。索引 stemming token,展示仍用
_source原文。 - stop words 谨慎。停用词有时承载查询语义("not""to""between")。
- 同义词放搜索期。词表变化频繁时不要把业务词表烧进倒排索引。
- ngram 只用于短字段或受限前缀。全字段 ngram 通常制造索引灾难。
- 已有索引不能随便改 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 章)