1. 脚本

原文链接 : http://www.apache.wiki/display/Elasticsearch/Scripting（修改该链接为官网对应的链接）

译文链接 : http://www.apache.wiki/display/Elasticsearch/Scripting

贡献者 : 阿叩，ApacheCN，Apache中文网

MarkDown文件：Scripting.md

1.1. 脚本

脚本模块能够帮你通过脚本来自定义表达式求值。例如，你可以使用脚本作为搜索请求的一部分返回“脚本字段”或自定义一个评分查询。

默认脚本语言为Painless。您能够通过添加lang插件来启用其他语言编写的脚本。任何使用脚本的地方，您都可以通过设置lang参数来指定脚本的语言。

1.2. 普通语言

这些语言可以用于任何的脚本API，并给予了最大的灵活性。

1.3. 专业语言

这些语言不太灵活，但对于某些任务通常有更高的性能。

脚本与安全（警告）

语言在设计时是考虑到安全沙盒的。然而，非沙盒语言可能是一个安全问题，请阅读脚本与安全来获取详细信息。

脚本使用

在es API中支持脚本的地方，语法遵循相同的模式：

"script": {

"lang": "...", （1） "inline" | "stored" | "file": "...", （2） "params": { ... } （3） }

（1）写入脚本的语言，默认为painless。

（2）脚本可以指定为 inline, stored, or file.

（3） 传递给脚本的命名参数。

eq:下面脚本是查找请求 返回scripted field: PUT my_index/my_type/1 { "my_field": 5 }

GET my_index/_search { "script_fields": { "my_doubled_field": { "script": { "lang": "expression", "inline": "doc['my_field'] * multiplier", "params": { "multiplier": 2 } } } } }

参数

lang 指定脚本写入的语言，你可以设置任何脚本语言，可以通过改变config 文件下 elasticsearch.yml 设置成script.default_lang 合适的语言

inline, stored, file

指定脚本的源 inline脚本入上面eg所示 stored 指定存储在集群(see Stored Scripts 超连接)并从config / scripts目录中的文件检索文件脚本（请参阅文件脚本）。

虽然众多表达式和painless 语言可以作为inline或存储的脚本配置即可用，但其他例如groovy的语言只能被指定为文件，除非您首先调整默认的脚本安全设置。

params 指定作为变量传递到脚本中的任何命名参数。

prefer 参数 Elasticsearch第一次使用脚本 编译并且存在在cache中 可能是一个复杂的过程 如果您需要将变量传递到脚本中，那么您应该将它们作为命名参数传递，而不是将其转换为脚本本身的编码。 eg，如果您想要实现不同的乘数乘以一个字段值，则不要将乘法器编码在脚本中

"inline": "doc['my_field'] 2" 命名参数传递： "inline": "doc['my_field'] multiplier", "params": { "multiplier": 2 }

每次乘法器更改时，必须重新编译一次版本。

如果编译了太多的独特脚本，Elasticsearch将会以circuit_breaking_exception错误拒绝动态脚本。 默认情况下，每分钟最多可编译15个内联脚本。 您可以通过设置script.max_compilations_per_minute来动态更改此设置。

file 基本脚本 为了提高安全性，只能在集群中每个节点上存储的脚本文件中指定语言。 文件脚本必须保存在scripts 目录中，其默认位置取决于是否使用zip / tar.gz（$ ES_HOME / config / scripts /），RPM或Debian软件包。 默认值可以通过path.scripts设置更改。

默认情况下语言是：painless, expression, and mustache（用于搜索和查询模板）。

脚本目录中放置的任何文件将在节点启动后自动编译，every 60 seconds thereafter。

该文件应该命名如下：{script-name}。{lang}。 例如，以下示例创建一个名为calculate-score的calculate-score：

cat "log(_score * 2) + my_modifier" > config/scripts/calculate-score.groovy

脚本可以使用下面的 GET my_index/_search { "query": { "script": { "script": { "lang": "groovy", （1） "file": "calculate-score", (2) "params": { "my_modifier": 2 } } } } }

1.脚本的suffix（后缀） 2.file的名字

脚本目录可能包含子目录，在这种情况下，目录的层次结构将被连接。 group1 / group2 / my_script.groovy中的脚本应该使用group1_group2_myscript作为文件名。

自动脚本重载

脚本目录将每60秒重新扫描一次（可以使用resource.reload.interval设置进行配置），新脚本，已更改或已删除的脚本将从脚本缓存中进行编译，更新或删除。

脚本重新加载可以通过将script.auto_reload_enabled设置为false来完全禁用。

脚本存储 脚本可以使用_scripts终点存储在集群状态并从集群状态中检索。

弃用的命名空间 使用lang和id作为唯一标识符的存储脚本的命名空间已被弃用。存储脚本的新命名空间只能使用id。存储的脚本具有相同的id，但不同的lang的将不再允许在6.0。要遵守存储脚本的新命名空间，现有存储的脚本应该被删除并重新放置。任何共享id但具有不同“lang”的脚本将需要重新命名。例如，请执行以下操作：

“id”：“example”，“lang”：“painless”“id”：“example”，“lang”：“表达式”

上述脚本将在新的命名空间下冲突，因为id是相同的。至少有一个必须被重新命名才能遵守id的新命名空间。

作为最后的注意事项，存储的搜索模板和存储的脚本共享相同的命名空间，因此，如果搜索模板与存储的脚本具有相同的标识，则必须使用delete和put请求重新命名其中的一个。 请求的eg /_scripts/{id} 备注：id为唯一值、

在群集状态中存储一个名为calculate-score的 painless 脚本： POST _scripts/calculate-score { "script": { "lang": "painless", "code": "Math.log(_score * 2) + params.my_modifier" } }

和上面一样的效果的 GET _scripts/calculate-score

存储脚本可以利用下面的例子

GET _search { "query": { "script": { "script": { "stored": "calculate-score", "params": { "my_modifier": 2 } } } } }

deleted DELETE _scripts/calculate-score

查询缓存

默认情况下，所有脚本都被缓存，因此只有当更新发生时才需要重新编译。 文件脚本保留静态缓存，并始终驻留在内存中。 内联和存储的脚本都存储在可以驱逐驻留脚本的缓存中。 默认情况下，脚本没有时间到期，但您可以使用script.cache.expire设置更改此行为。 您可以使用script.cache.max_size设置来配置此缓存的大小。 默认情况下，缓存大小为100。

存储脚本的大小限制为65,535字节。 这可以通过设置script.max_size_in_bytes设置来更改，以增加限制，但是如果脚本真的很大，那么应该考虑替代native 脚本。

请求文档文件和特殊变量 根据使用脚本的位置，它可以访问某些特殊变量和文档字段。

cix._source 反问文档_source field cix.op index or delete ctx._index document meta-fields 访问

查询聚合脚本 除了每个搜索命中执行一次的脚本字段外，搜索和聚合中使用的脚本将针对可能与查询或聚合匹配的每个文档执行一次。 根据你有多少文件，这可能意味着数百万或数十亿的执行：这些脚本需要快！

可以使用文档值或存储的字段或_source字段从脚本访问字段值，这些位置如下所述。

脚本还可以访问文档的相关性_score，并通过实验_index变量访问高级文本评分的术语统计信息。

访问score（评分）文档的脚本

在function_score查询，基于脚本的排序或聚合中使用的脚本可以访问表示文档当前相关性分数的_score变量。

以下是使用function_score查询中的脚本更改每个文档的相关性_score的示例：

PUT my_index/my_type/1 { "text": "quick brown fox", "popularity": 1 }

PUT my_index/my_type/2 { "text": "quick fox", "popularity": 5 }

GET my_index/_search { "query": { "function_score": { "query": { "match": { "text": "quick brown fox" } }, "script_score": { "script": { "lang": "expression", "inline": "_score * doc['popularity']" } } } } }

doc values

到目前为止，从脚本访问字段值最快最有效的方法是使用doc ['field_name']语法，它从doc值检索字段值。 文档值是一个列字段值存储，默认情况下在除分析文本字段之外的所有字段上启用。

PUT my_index/my_type/1 { "cost_price": 100 }

GET my_index/_search { "script_fields": { "sales_price": { "script": { "lang": "expression", "inline": "doc['cost_price'] * markup", "params": { "markup": 0.2 } } } } }

如果字段为多值，则文档值只能返回“简单”字段值，如数字，日期，地理位置，术语等，或这些值的数组。 它不能返回JSON对象。

文档值和text 字段

如果启用了fielddata，则doc ['field']语法也可用于分析的文本字段，但BEWARE：在文本字段上启用fielddata需要将所有术语加载到JVM堆中，这可能非常昂贵 内存和CPU。 从脚本访问文本字段很少有意义。

存储字段和_source 存储字段 - 明确标记为“store”的字段：true - 可以使用_fields ['field_name']。或_fields ['field_name']。值语法访问。

可以使用_source.field_name语法访问真正只是特殊存储字段的文档_source。 _source被加载为map-of-maps，因此可以访问对象字段内的属性，例如.first。

prefer 储存字段文档值

存储的字段（包括存储的_source字段）比doc值慢得多。 它们被优化为每个结果返回几个字段，而doc值被优化用于访问许多文档中特定字段的值。

在从搜索结果生成前十个匹配的脚本字段时使用_source或存储字段是有意义的，但对于其他搜索和聚合用例，总是更喜欢使用doc值。 eg PUT my_index { "mappings": { "my_type": { "properties": { "title": { （1） "type": "text" }, "first_name": { "type": "text", "store": true }, "last_name": { "type": "text", "store": true } } } } }

PUT my_index/my_type/1 { "title": "Mr", "first_name": "Barry", "last_name": "White" }

GET my_index/_search { "script_fields": { "source": { "script": { "inline": "params._source.title + ' ' + params._source.first_name + ' ' + params._source.last_name" }（2） }, "stored_fields": { "script": { "inline": "params._fields['first_name'].value + ' ' + params._fields['last_name'].value" } } } }

1.标题字段不存储，因此不能与_fields []语法一起使用。 2.标题字段仍然可以从_source访问。

stored 和_source 比较 _source字段只是一个特殊的存储字段，因此性能与其他存储字段的性能相似。 _source提供对索引的原始文档主体的访问（包括区分空值和空字段的能力，单值数组从平坦标量等）。

使用存储字段而不是_source字段唯一有意义的是，当_source非常大时，访问一些小的存储字段而不是整个_source成本较低。

脚本的安全

您不能用root用户身份运行Elasticsearch，因为这将允许脚本在您的服务器上访问或执行任何操作，而不受限制。

您不应该将Elasticsearch直接显示给用户，而是在其间具有代理应用程序。 如果您打算将Elasticsearch直接显示给用户，那么您必须决定是否信任足够的脚本来运行脚本，并应用相应的安全措施。

script.*设置允许对哪些脚本语言（例如，groovy，painless）被允许运行在哪个上下文（例如 search，aggs，update）以及允许脚本来源的位置（即 inline stored file）。进行细粒度控制

例如，以下设置可将存储的更新脚本用于groovy：

script.engine.groovy.inline.update: true

存在不太细粒度的设置，允许您为所有源，所有语言或所有上下文启用或禁用脚本。 以下设置为所有上下文中的所有语言启用内联和存储的脚本：

script.inline: true script.stored: true

上述设置意味着任何可以向Elasticsearch实例发送请求的人都可以运行任何他们选择的脚本！ 这是一个安全风险，可能会导致您的Elasticsearch集群受到威胁。

脚本源设置

脚本可能会被启用或禁用，具体取决于它们的来源：内联，存储在群集状态，或者来自集群中每个节点上的文件。 这些设置中的每一个都需要以下值之一：

false 脚本停止

true 脚本启动

默认是

script.inline: false script.stored: false script.file: true

全局脚本设置会影响到 mustache 脚本语言。 搜索模板内部使用mustache 语言，并且默认情况下仍将启用sandboxed， 但会根据elasticsearch.yml中指定的细粒度设置启用/禁用。

脚本文档的设置

还可以在Elasticsearch API的不同上下文中启用或禁用脚本。 支持的上下文是：

aggs：聚合 search：查询 update 更新 plugin 插件

插件还可以定义他们使用脚本的自定义操作，而不是使用通用插件类别。 这些操作可以以下列形式引用：$ {pluginName} _ $ {operation}。

以下示例将禁用更新和插件操作的脚本，而不管脚本源或语言如何。 脚本仍然可以从沙盒语言执行，作为聚合，搜索和插件执行的一部分，因为上述默认值仍然被应用。 script.update: false script.plugin: false

细粒度脚本设置 首先，按顺序应用上述的高级脚本设置（上下文设置优先于源设置）。 然后，包含脚本语言的细粒度设置优先于任何高级设置。

细粒度设置的格式如下：

script.engine.{lang}.{source}.{context}: true|false

and script.engine.{lang}.{inline|file|stored}: true|false

eg： script.inline: false 1 script.stored: false 2 script.file: false 3

script.engine.groovy.inline: true 4 script.engine.groovy.stored.search: true 5 script.engine.groovy.stored.aggs: true 6

script.engine.mustache.stored.search: true 7

1关闭脚本的源 4启动inline脚本运行 5启动存储查询聚合 7启动存储mustache 查询

Java安全管理 默认情况下启用Java Security Manager运行Elasticsearch。 Elasticsearch中的安全策略将授予每个类的权限锁定到操作所需的最低限度。 这样做的好处是它严重限制了黑客可用的攻击向量。

限制权限对于Groovy和Javascript这样的脚本语言尤为重要，这些脚本语言旨在执行Java本身可以完成的任何操作，包括写入文件系统，将套接字打开到远程服务器等。

脚本类加载器白名单 脚本语言只允许加载出现在可以在org.elasticsearch.script.ClassPermission中找到的编码的白名单中的类。

在脚本中，尝试加载未显示在白名单中的类可能会导致ClassNotFoundException异常，例如此脚本：

GET _search { "script_fields": { "the_hour": { "script": "use(java.math.BigInteger); new BigInteger(1)" } } }

返回下面

{ "reason": { "type": "script_exception", "reason": "failed to run inline script [use(java.math.BigInteger); new BigInteger(1)] using lang [groovy]", "caused_by": { "type": "no_class_def_found_error", "reason": "java/math/BigInteger", "caused_by": { "type": "class_not_found_exception", "reason": "java.math.BigInteger" } } } }

然而，类加载器问题也可能导致更难以解释异常。 例如，这个脚本： use(groovy.time.TimeCategory); new Date(123456789).format('HH')

返回下面 { "reason": { "type": "script_exception", "reason": "failed to run inline script [use(groovy.time.TimeCategory); new Date(123456789).format('HH')] using lang [groovy]", "caused_by": { "type": "missing_property_exception", "reason": "No such property: groovy for class: 8d45f5c1a07a1ab5dda953234863e283a7586240" } } }

处理Java安全管理器问题 如果您遇到Java安全管理器的问题，您有两个解决这些问题的选项：

修复安全问题 最安全和最安全的长期解决方案是更改导致安全问题的代码。 我们认识到这可能需要时间才能正确进行，因此我们提供以下两种选择。

自定义类加载器whitelistedit 可以通过调整本地Java安全策略来定制类加载器白名单：

系统范围：$ JAVA_HOME/lib/security /java.policy， 仅用于弹性搜索用户：/home/elasticsearch/.java.policy 通过将系统属性添加到jvm.options配置中：-Djava.security.policy = someURL，或 通过带有-Djava.security.policy = someURL的ES_JAVA_OPTS环境变量：

export ES_JAVA_OPTS="${ES_JAVA_OPTS} -Djava.security.policy=file:///path/to/my.policy` ./bin/elasticsearch

可以在类，包或 级别授予权限。 例如：

grant { permission org.elasticsearch.script.ClassPermission "java.util.Base64"; // allow class permission org.elasticsearch.script.ClassPermission "java.util."; // allow package permission org.elasticsearch.script.ClassPermission ""; // allow all (disables filtering basically) };

以下是如何启用groovy.time.TimeCategory类的示例：

grant { permission org.elasticsearch.script.ClassPermission "java.lang.Class"; permission org.elasticsearch.script.ClassPermission "groovy.time.TimeCategory"; };

在向白名单添加class之前，请考虑它对Elasticsearch的安全影响。 你真的需要一个额外的类，或者你的代码可以以更安全的方式重写？

我们很可能没有将一般的有用和安全的class列入白名单。 如果你有一个你认为应该被列入白名单的class，请在GitHub上打开一个问题，我们将考虑这样做的影响。