聊Elasticsearch性能问题聊到最后大概率绕不开DocValues而DocValues对外暴露的每一个读接口背后LeafDocLookup才是真正干活的角色。很多同学在Painless脚本里写过doc[order_amount].value在查询里加过docvalue_fields但问起Elasticsearch是怎么按文档ID把列存的值取出来的能说清楚的人其实不多。这篇就来把LeafDocLookup讲透它是什么、内部怎么工作、脚本里随手写的代码为什么有时快有时慢以及报错时怎么排查。适合正在折腾ES脚本查询、聚合性能或者想写插件但卡在字段读取上的开发者。1. LeafDocLookup 到底是什么从一次查询说起假设你有一个订单索引跑一条带脚本的排序查询按用户累计订单金额排序同时过滤掉金额小于100的。Elasticsearch收到请求后会先走查询阶段拿到命中的文档ID集合到聚合或排序阶段再拿着这些文档ID去找具体的字段值。这个“拿着文档ID找字段值”的动作正是LeafDocLookup的核心职责。1.1 段、LeafReader、doc ID绕不开的三板斧要理解LeafDocLookup先得记住Lucene的一个基本结构索引由一个或多个段组成段是冻结的不可变文件集合。每个段在搜索时被包装成一个LeafReaderElasticsearch的分片相对用户是一个索引底层其实是多个段轮流接受查询。每个文档在某个段内部都有一个局部文档号locDocID范围从0到段内文档数减一。LeafDocLookup名字里的“Leaf”就是指它工作在某个LeafReader之上只负责自己所在这个段的数据。正因为Elasticsearch不知道你会命中哪个段所以在查询过程中会为每个段分别构建对应的LeafFieldData再从中取出LeafDocLookup。你可以把段理解成图书馆里的一排书架LeafDocLookup就是贴在每层书架上的索引卡。找书时先定位到正确的书架再根据索引卡快速翻到那一页。1.2 doc values 与 LeafDocLookup 的关系这里有个常见的误解把DocValues和LeafDocLookup当成一回事。严格来说DocValues是Lucene提供的列式存储能力同一字段的所有值按doc ID顺序紧挨着放在一起磁盘上可以顺序读内存中可以映射访问。而LeafDocLookup是Elasticsearch在DocValues之上封装的一层按文档取值的查询器。为什么不能直接拿Lucene的DocValues用因为Lucene的DocValues接口暴露的是底层游标而脚本、排序、聚合这些场景需要一套更稳定、更面向“当前文档”的语义。比如Painless脚本里写doc[price].valueElasticsearch要先知道当前脚本正在处理哪个文档再调用LeafDocLookup把该文档段内的值定位出来并转成Java对象。如果没有这层封装脚本代码会跟Lucene的游标细节耦合在一起维护性很差。1.3 为什么 Elasticsearch 需要一层“文档值查找器”再说深一层分布式系统里Elasticsearch经常要在数据节点上做并行计算每次查询都可能触发几十万个文档的字段值读取。如果每个脚本变量都直接操作底层Lucene对象首先要解决“当前文档ID”这个上下文问题。Lucene的DocValues是顺序访问模型而脚本要求随机访问。LeafDocLookup把顺序游标包装成随机访问接口每次只要告诉它“我现在要读docId10086”它就帮你定位并取回该文档的值。另外不同字段类型在底层存储格式完全不同数值型可能走压缩数组字符串型走字典序编码多值字段还要维护一个文档对应多个值的映射。如果没有统一封装用户脚本里doc[score]和doc[tag]的取值体验会完全割裂。LeafDocLookup通过统一的setDocument(int docId)驱动和getValue()取值语义把这些差异掩盖在内部实现里这才是它真正值钱的地方。2. 核心机制拆解LeafDocLookup 的内部结构与工作流程理解了这个组件的定位我们深入到源码级别的调用链。这里不要求你把每行源码都记住但这个流程理顺了后面排查问题会轻松很多。2.1 从 IndexFieldData 到 LeafFieldData 再到 LeafDocLookup在Elasticsearch的字段数据体系里关系是层层递进的。索引级的IndexFieldData负责管理整个索引某个字段的访问策略它提供一个方法getLeafFieldData(LeafReaderContext)返回LeafFieldData。LeafFieldData是段级别的字段数据里面可以拿到两样东西一个是getScriptValues()返回的就是ScriptDocValues另一个是getAtomicReader()用于读取底层Lucene文档数据。LeafDocLookup正是ScriptDocValues的默认实现类。它内部持有三样东西一个DocValues实例、一个当前文档ID的指针、以及一个预分配的值缓存数组。每当脚本要读取数据Elasticsearch会先把这个文档ID写入LeafDocLookup再触发其内部的DocValues对象做advance到目标文档随后把结果打包成数组或者单值返回。有一个小细节值得注意LeafDocLookup在处理单值字段时底层用的是NumericDocValues它本身支持直接随机定位但多值字段用的是SortedNumericDocValues底层是稠密有序数组加偏移表定位时同样要看文档的起始偏移和值数量。Elasticsearch之所以把这些细节都藏起来就是让上层代码只认get(int index)和getValue()两个动作脚本可读性才够好。2.2 单值与多值字段setDocument 与值游标单值字段和多值字段在LeafDocLookup里是完全不同的两套游标逻辑。对于单值字段一次setDocument之后getValue()直接返回那个唯一的值。对于多值字段情况要复杂一些。举例来说一个订单可以有多个标签映射里把tags定义成keyword且doc_values: true那么同一文档在LeafDocLookup内部会维护一个List结构。脚本里doc[tags].size()返回该文档的标签个数doc[tags].get(0)返回第0个标签doc[tags].value返回的则是内部排序后的第一个值。这里有个特别容易踩的坑多值字段的value返回的并不是录入时的第一个值而是DocValues内部有序排列后的第一个值。因为Lucene的SortedSetDocValues用字典序组织文本SortedNumericDocValues用数值升序组织数值。你以为自己在读原始录入顺序实际上读的是存储顺序。如果你的业务强依赖字段录入顺序千万别用doc[field].value老老实实遍历get(i)或者重新设计你的数据结构。心法就是每次setDocument相当于把游标移动到指定的文档行之后所有取值操作都针对这一行。脚本执行过程中这个当前文档ID是由外部驱动不断更新的并不是LeafDocLookup自己内部维护一个全局状态之后问完不动。2.3 数据类型对应的 DocValues 实现从源码角度看Elasticsearch对不同字段类型会构造不同的DocValues实现字段类型DocValues实现底层存储long/integer/short/byteSortedNumericDocValues数值数组按doc分段double/floatSortedNumericDoubleDocValues数值数组double编码keyword单值SortedDocValuesordinal字典 字典排序列keyword多值SortedSetDocValuesordinal集合 偏移表binaryBinaryDocValues字节内容存储同样是LeafDocLookup字段类型不同、多值约束不同内部取值的开销差异巨大。数值型多值字段在64位代价上几乎可以忽略而字符串多值字段则多了一次ordinal转原字符串的操作。这就是为什么在脚本里频繁访问大字符串字段比访问数值字段明显更慢。能接受的话最好先做一层数值编码或者用keyword做字典排序后的辅助过滤避免脚本在海量distinct字符串之间反复做转换。3. 使用场景与实操脚本、docvalue_fields 和排序中的 LeafDocLookup理论讲完落到实操。大部分开发者真正关心的是我在脚本里怎么写、怎么调优、怎么避免踩坑。3.1 Painless 脚本中如何真正用到它最常见的实操场景是Painless脚本。比如计算近30天订单总额超过5000的用户或者统计用户订单状态机里各状态之间的金额占比。Painless脚本语法本身就支持doc[order_amount]这样的写法这行代码经过ES编译后最终会落到LeafDocLookup相关接口上。来看一个完整的示例。假设mapping如下{ mappings: { properties: { user_id: { type: keyword }, order_amount: { type: long, doc_values: true }, sku_ids: { type: keyword, doc_values: true } } } }然后脚本def amountDoc doc[order_amount]; double total 0; for (int i 0; i amountDoc.size(); i) { total (double) amountDoc.get(i); } return total 5000;这里amountDoc就是一个LeafDocLookup的脚本侧引用。注意我把doc[order_amount]先赋值到局部变量amountDoc这是脚本优化的第一个关键动作。如果循环里每次都写doc[order_amount].get(i)等于每次都要重新走一遍从属性入口查找字段数据、做类型判断、包一层对象的流程而局部变量只做一次字段解析后续全在同一个对象上取数。性能差距在大量文档上能到两三倍。3.2 脚本性能怎么优化filter前置、doc values开关与局部变量有了LeafDocLookup做底脚本优化的几个方向就很清晰了。第一能用query过滤的绝不放进脚本。脚本执行是逐文档遍历查询过滤在Lucene底层可以走位图和倒排索引两者复杂度不在一个量级。写脚本前先自查一下能不能把金额大于100改成range过滤再在脚本里只做金额累加在很多业务里能省掉90%以上文档字段值的读取。第二确认字段的doc_values真的开着。Elasticsearch在mapping里默认对keyword、数值、日期等字段开启doc_values: true但text字段默认不开。如果你的字段映射被改成了doc_values: false脚本访问会报错或者更糟回退到从_source加载给你一种能跑但很慢的错觉。第三一次脚本只取必要字段。LeafDocLookup按字段粒度加载脚本里访问三个字段就意味着三个DocValues对象都要做游标推进。如果你只用到两个字段那就别在脚本里为了顺手把第三个字段也读进来。这个问题在复杂聚合脚本里极其常见脚本里塞了五六个doc[xxx]实际用到的只有两个。3.3 搜索返回时用 docvalue_fields 与 runtime fields除了脚本日常查询也会间接用到LeafDocLookup。最常见的场景是搜索结果的source过滤特别是大字段你不希望每次都返回_source里那份巨大的原始JSON而是直接取某几个字段的值。这时可以在请求里加docvalue_fields{ fields: [ order_no, order_amount, sku_ids ] }这个方案底层就是通过DocValues读取对应字段与LeafDocLookup同样的机制区别是它不经过脚本直接按doc ID解析字段值。优点是速度快、内存可控也不涉及脚本编译缺点是你只能拿到doc values里存的原始形式无法像脚本那样对值做加工。还有一类场景也跟它相关runtime fields。当定义runtime字段并且设置type: long, script访问doc[source_field]时实际上是在查询执行阶段临时构建DocValues访问链路底层同样依赖LeafDocLookup这样的组件。runtime字段给了你动态变更线上mapping的灵活性但它每次查询都要重新计算性能上限通常不如原生doc values字段。对于稳定查询能用mapping解决的就不要迷信runtime。4. 常见问题与排查技巧实录最后这部分把我在实际项目里遇到过的典型问题整理出来按报错现象、排查思路、解决方案的顺序说。4.1 报错 Text fields are not optimised...这是最经典的报错几乎每个ES开发都见过。当你在text字段上跑聚合或用doc[title].value时Elasticsearch会返回类似下面的错误{ error: { type: illegal_argument_exception, reason: Text fields are not optimised for operations that require per-document field data, like aggregations and sorting, so these operations are disabled by default. Please use a keyword field instead. Alternatively, set fielddatatrue on [title] in order to load field data by uninverting the inverted index. Note that this can use significant memory. } }原因很直接text字段要被分词原始完整文本无法按doc ID排列成紧凑的列式存储。Lucene只为它建了倒排索引而不是列式存储的DocValues。倒排索引是用来回答哪些文档包含某个词的你要反过来按文档找这个文档的原文是什么只能把倒排索引反转加载到内存这就是fielddata机制。Elasticsearch默认不建议这么干因为内存代价太高。遇到这种报错正确解法是给text字段配一个keyword子字段用keyword子字段做聚合和脚本。只有当你确定该字段用于全文检索的文本量非常小内存可控时才考虑打开fielddata开关而且设置后要重点监控堆内存增长。我的建议很直白能不开就不开用keyword子字段永远是优先解。4.2 fielddata 与 doc values 的内存陷阱脚本查询慢很多时候不是LeafDocLookup本身慢而是你无意中把fielddata给启用了。fielddata是把分词后的倒排索引反转为文档ID到词项的映射全部装进JVM堆不是面向磁盘列存的设计而doc values走OS页缓存或磁盘顺序读。两者都可以封装成LeafDocLookup进行读取但内存模型完全不同。把这两类访问方式做个对比对比维度doc valuesfielddata存储位置磁盘为主映射到页缓存JVM堆内存打开方式mapping中doc_values: truemapping中fielddata: true默认状态大多数字段默认开启默认关闭适用场景列式聚合、排序、脚本针对text的旧式访问常见问题磁盘IO、段级加载堆内存膨胀、GC停顿如果发现fielddata缓存一直在涨先执行字段数据统计接口看哪些字段占用了空间然后要么关闭该字段的fielddata要么在索引设置里限制indices.fielddata.cache.size。同样地因为doc values是磁盘加载集群层面要留意段文件扫描和页缓存的命中率好好调整节点的内存分配避免数据节点上频繁做磁盘预读。4.3 跨段合并与 refresh 对 LeafDocLookup 的影响还有一个大家容易忽视的细节LeafDocLookup只对单个段有效。当触发refresh产生新段或者段合并把多个小段合并成一个大段时同一批文档的doc ID会发生变化。好在Elasticsearch每次查询都是先拿到当前可用的Segment集合再为每个Segment构建对应的字段数据缓存所以正常情况下你根本感知不到这个变化LeafDocLookup总是在查询上下文中被重新构造。但是如果你做的是长生命周期的高性能客户端比如在插件或自研查询引擎里缓存了LeafReaderContext或LeafFieldData就要千万小心缓存跨refresh后路径可能失效。最佳实践是按版本号或者SegmentCommitInfo的id做缓存key一旦检测到索引有新提交就主动重建LeafDocLookup的引用。我早期在做一个字段统计插件时就因为缓存了LeafFieldData没有及时刷新导致查询结果偶尔出现明明有数据但读不到值的诡异现象排查了两天才发现是缓存失效问题。最后再分享一个定位技巧如果问题限定在某个脚本查询上先简化脚本逐步注释掉doc[xxx]访问看哪个字段是瓶颈再看该字段的类型和多值约束最后用profile API查看查询执行细节。把这三个步骤走完绝大部分脚本慢的问题都能定位。我个人在实际操作中还有个小偏好凡是核心查询里高频访问的字段mapping都会把doc_values固定为true同时禁用fielddata再配合keyword子字段做聚合。这样LeafDocLookup这层封装走的一直是磁盘列存的正路内存开销可控脚本查询也能维持稳定的延迟。如果你也在写ES插件或者维护高吞吐的聚合查询建议花半小时把项目里所有doc[xxx]的访问模式翻一遍你大概能发现不少可以优化的隐藏收益。