Elasticsearch 把 Painless 作为默认脚本语言后，脚本的编写门槛确实降低了不少。它的语法和 Java 很接近，变量声明、条件判断、循环结构都能直接套用。但 Painless 不是完整的 Java，它在沙箱中运行，去掉了反射、系统命令、动态类加载等高危能力，同时对循环次数也有上限。这意味着脚本更像一个受控的表达式计算器，而不是可以自由调用任意 API 的程序。写查询脚本时最常见的两个对象是 doc 和 params，写更新脚本时则主要操作 ctx._source。如果分不清这几个对象，脚本要么读取字段失败，要么把源文档改错。
一、字段访问：doc、params 与 _source 的边界
doc 对象用于读取文档的字段值，它直接建立在 doc values 之上，适合在查询、排序和聚合脚本中使用。你需要注意的是，doc['field'] 返回的不是一个简单的数值，而是一个字段访问器。只有调用 .value 之后，才会得到实际值。对于多值字段，可以用 doc['field'].values 拿到集合。如果字段在文档中不存在，直接访问 doc['field'].value 会抛出异常，这是脚本报错的高发点。稳妥的做法是先用 size() 判断长度，再决定是否取值。
if (doc['price'].size() != 0) {
return doc['price'].value;
} else {
return 0;
}
与 doc 不同，params 对象存放的是外部传入的参数。它不是文档字段，而是由查询语句中的 params 段提供。把阈值、权重、标签等变量放在 params 里，而不是直接拼接到脚本源码中，是 Painless 性能优化的第一步。因为脚本编译缓存以脚本源码为 key，源码不变时参数变化不会引发重新编译。如果脚本内容是 return doc['price'].value > 100;，那么把 100 改成 200 就会生成一份新源码；而改成 return doc['price'].value > params.min_price; 后，同一段脚本可以反复使用。
if (doc['price'].size() != 0 && doc['price'].value > params.min_price) {
return true;
}
return false;
还有一种字段访问方式是读取 _source。它返回的是原始 JSON 文档，可以读取 text 类型字段、嵌套对象以及未被索引的字段。但 _source 需要反序列化原始 JSON，读取成本远高于 doc。在查询和排序场景中，能使用 doc 就尽量不用 _source。更新文档时，则要用 ctx._source，因为这个对象直接对应即将写回索引的源数据。
二、脚本查询与排序：参数化是缓存的关键
脚本查询通常在 script 查询中执行，返回布尔值。一个常见场景是判断某个字段是否超过动态阈值。把阈值通过 params 传入，要比拼接数值更安全。试想从 Web 接口接收用户输入并直接写入脚本，不仅会让缓存频繁失效，还可能被注入恶意脚本片段。虽然 Elasticsearch 默认不允许动态脚本，但参数化可以进一步降低风险。
脚本排序的思路类似，只不过返回的是参与排序的数值。例如要按销量和评分综合排序，可以用下面这段脚本。它逐个判断字段是否存在，不存在的字段按 0 处理，避免因为空值导致整条排序失败。
double score = 0;
if (doc['sales'].size() != 0) {
score += doc['sales'].value;
}
if (doc['rating'].size() != 0) {
score += doc['rating'].value * 2;
}
return score;
这里还要强调一点：脚本排序会对命中的文档逐条执行，数据量大时开销非常明显。如果排序字段本身是数值类型，优先使用原生 sort 加 mode 或 nested 配置。只有在多个字段需要按复杂公式计算时，才考虑脚本排序。并且排序脚本里不要读取 _source，否则每次都要解析 JSON，性能会进一步下降。
三、更新场景：ctx._source 的正确用法
更新脚本通过 ctx 对象访问文档上下文。ctx._source 是当前文档的源数据，可以把它理解为一个可变的 Map。常见错误是直接写 ctx._source = params.new_value;，这会把整个源文档替换掉，而不是修改某个字段。正确做法是使用 put、remove、add 等方法操作具体字段。下面是一个给标签字段去重后追加值的示例。
if (ctx._source.tags == null) {
ctx._source.tags = [];
}
if (!ctx._source.tags.contains(params.tag)) {
ctx._source.tags.add(params.tag);
}
如果标签字段可能不是数组，比如某些历史文档把它写成了字符串，上面的脚本会出现类型转换问题。更健壮的方式是先判断 ctx._source.tags 是否是集合类型，或者统一在写入前做好规整。对于删除字段，可以直接调用 ctx._source.remove(params.field_name);。要在脚本中删除整个文档，则可以设置 ctx.op = 'delete';，这比从更新 API 中发送删除请求更灵活，适合按条件批量清理。
if (ctx._source.status == 'disabled') {
ctx.op = 'delete';
}
更新脚本还经常涉及空值判断。Elasticsearch 的源文档可能缺少某些字段，因此先把返回的 Map 或 List 做 null 检查，比直接调用方法更可靠。需要注意的是，ctx._source 的内容在脚本中修改后，Elasticsearch 会重新索引整个文档。如果脚本没有实际修改数据，可以返回 ctx.op = 'noop';，以减少不必要的写入和版本冲突。
四、性能与安全：Painless 不是万能 DSL
Painless 提供了很大的灵活性，但灵活性的代价是性能。脚本过滤、脚本字段和脚本排序都需要对命中文档逐条计算，而原生 DSL 可以利用倒排索引、BKD 树等结构快速过滤。很多查询用 range、term、bool 组合就能表达清楚，完全没有必要套一层脚本。可以先通过原生条件把候选文档集缩小，再对少量文档执行脚本，这样既保留灵活性，又避免全量扫描。
另一个容易忽视的问题是编译频率。Elasticsearch 对脚本编译有速率限制，默认参数为 script.max_compilations_rate。如果每个请求都使用内容略有不同的脚本，比如把用户 ID 或时间戳拼接在代码里，编译请求会迅速堆积，节点可能出现 too many dynamic script compilations 这样的错误。解决方式就是前面反复强调的参数化：脚本源码保持稳定，变化部分都走 params。
安全方面，除了避免拼接不可信输入，还应该限制脚本可读写的字段范围。对涉及敏感信息的索引，要结合字段级权限和角色控制，确保脚本只能访问必要字段。定期审查脚本查询也很重要，尤其是 _source 读取和正则表达式，这类操作容易放大单次请求的成本。合理的做法是：能用 DSL 就不写脚本，必须写脚本就保持简单、参数化、字段访问明确，并给脚本加上执行计划监控。
Elasticsearch Painless脚本编写安全高效修改时间：2026-09-26 09:48:39