Elasticsearch:如何在 Elasticsearch 中轻松编写 Painless 脚本

2022年2月24日   |   by mebius

你可以在我之前的文章 “Elastic:开发者上手指南” 的 “Painless 编程” 章节里找到许多介绍 Elasticsearch Painless 脚本编程的教程。在那些文章中,我大量地介绍了许多的使用案例。在今天的文章中,我更着重于介绍 Painless 这个脚本语言的语法。这个是在之前的文章中缺少的一部分。

随着 Elasticsearch 5.x 及以后版本的推出,我们获得了一种新的脚本语言 Painless。 Painless 是一种由 Elastic 开发和维护并针对 Elasticsearch 进行优化的脚本语言。 虽然它仍然是一种脚本语言,但其核心 Painless 被宣传为一种快速、安全、易于使用和安全的语言。

在本文中,我们将为你简要介绍 Painless,并向你展示如何在搜索和更新数据时使用该语言。

Painless 简介

Painless scripting 的目标是让用户轻松编写脚本,尤其是当你来自 Java 或 Groovy 环境时。 虽然你可能不熟悉 Elasticsearch 中的脚本,但让我们从基础开始。

变量及数据类型

可以使用原始、引用、字符串、void(不返回值)、数组和动态类型在 Painless 中声明变量。 Painless 支持以下原始类型:byte、short、char、int、long、float、double 和 boolean。 它们以类似于 Java 的方式声明,例如 int i = 0; double a; boolean g = true;。

Painless 中的引用类型也与 Java 类似,只是它们不支持访问修饰符,但支持类似 Java 的继承。 这些类型可以在初始化时使用 new 关键字进行分配,例如在将 a 声明为 ArrayList 或简单地将单个变量 b 声明为 null Map 时,例如:

ArrayList a = new ArrayList();  
Map b;  
Map g = [:];  
List q = [1, 2, 3];  

在最新的 Kibana 中,它集成了一个叫做 Painless Lab 的环境来对我们的 Painless 脚本进行测试,比如:

%title插图%num

你可以参考我之前的文章 “Kibana:使用 Painless Lab 来测试代码”。

Lists 和 Maps 类似于数组(arrays),只是它们在初始化时不需要 new 关键字,但它们是引用类型,而不是数组。

字符串类型可以使用如下的方式来进行定义。 例如:

String a = "a";  
String u;

Painless 中的数组类型支持以 null 作为默认值的单维和多维数组。 与引用类型一样,数组是使用 new 关键字分配的,然后是类型和每个维度的一组括号。 可以像下面这样声明和初始化数组:

int[] x = new int[2];  
x[0] = 3;  
x[1] = 4;  

数组的大小可以是明确的,例如 int[] a = new int[2] 或者你可以使用以下命令创建一个值为 1 到 5 且大小为 5 的数组:

int[] b = new int[] {1,2,3,4,5};  

与 Java 和 Groovy 中的数组一样,数组数据类型在声明和初始化时必须有一个原始的数据类型(比如,byte,short 等)、字符串,甚至是动态的 def 数据类型定义。

def 是 Painless 支持的唯一动态类型。 它的作用是模仿它在运行时分配的任何类型的行为。 因此,在定义变量时:

def a = 1;  
def b = "foo"; 

在上面的代码中,Elasticsearch 将始终假定 a 是原始类型 int,值为 1,b 为字符串类型,值为 “foo”。 数组也可以用 def 分配,例如,注意以下几点:

def[][] h = new def[2][2];  
def[] f = new def[] {4, "s", 5.7, 2.8C};  

抛开变量,让我们看一下条件和运算符。

运算符及条件

如果你了解 Java、Groovy 或现代编程语言,那么 Painless 中的条件和使用运算符将会很熟悉。 Painless 文档包含与语言兼容的完整运算符列表,以及它们的优先顺序和关联性。 列表中的大多数运算符都与 Java 和 Groovy 语言兼容。 像大多数编程语言一样,运算符优先级可以用括号覆盖(例如 int t = 5+(5*5))。

在 Painless 中使用条件与在大多数编程语言中使用它们是相同的。 Painless 支持 if 和 else,但不支持 else if 或 switch。 对于大多数程序员来说,条件语句看起来很熟悉:

if (doc['foo'].value = 5) {  
    doc['foo'].value *= 10;
} 
else {  
    doc['foo'].value += 10;
}

Painless 还有 Elvis 运算符 ?:,它的行为更像 Kotlin 中的运算符,而不是 Groovy。 基本上,如果我们有以下情况:

x ?: y  

一个 Elvis 由两个表达式组成。 评估第一个表达式以检查是否为空值。 如果第一个表达式的计算结果为 null,则计算第二个表达式并使用其值。 如果第一个表达式的计算结果为非 null,则使用第一个表达式的结果值。 使用 elvis 运算符 ‘?:’ 作为条件运算符的快捷方式。用例:

List x = new ArrayList();      
List y = x ?: new ArrayList(); 
y = null;                      
List z = y ?: new ArrayList(); 

Methods

虽然 Java 语言是 Painless 获得大部分功能的地方,但并非 Java 标准库(Java 运行时环境,JRE)中的每个类或方法都可用。 Elasticsearch 有 Painless 可用的类和方法的白名单参考。 该列表不仅包括 JRE 提供的方法,还包括可用的 Elasticsearch 和 Painless 方法。

Painless Loops

Painless 支持 while、do…while、for 循环和控制流语句(如 break 和 continue),这些都在 Java 中可用。 Painless 中的 for 循环示例在大多数现代编程语言中看起来也很熟悉。 在下面的示例中,我们循环遍历包含文档 doc[‘scores’] 中分数的数组,并将它们添加到变量 total 中,然后返回它:

def total = 0;  
for (def i = 0; i 

将该循环修改为以下内容也将起作用:

def total = 0;  
for (def score : doc['scores']) {  
    total += score;
}
return total;  

现在我们已经了解了一些语言基础知识,让我们开始查看一些数据,看看我们如何将 Painless 与 Elasticsearch 查询结合使用。

装载数据

在将数据加载到 Elasticsearch 之前,请确保你设置了新的索引。 你需要在 Dev Tools 控制台、终端或使用你选择的编程语言中创建一个新索引。 我们将创建的索引称为 “sat”。 设置索引后,让我们收集数据。我们可以简单地在 Kibana Dev Tools 中打入:

PUT sat

我们将使用的数据是加州教育部编制的 2015/16 年度学校平均 SAT 成绩列表。 加州教育部的数据来自 Microsoft Excel 文件。 我们将数据转换为 JSON,可以从这里的 Github 存储库下载。

git clone https://github.com/liu-xiao-guo/elasticsearch-painless

下载 JSON 文件后,我们可以使用 Elasticsearch 的 Bulk API 将数据插入到我们创建的 “sat” 索引中。

curl -u username:password -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary @sat_scores.json 

在上面,你需要根据自己集群的用户名及密码进行修改。等运行完上面的命令后,我们可以看到:

GET sat/_count

我们可以发现有 2334 个文档:

{
  "count" : 2334,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  }
}

每个文档的字段如下:

GET sat/_search?filter_path=**.hits
{
  "hits" : {
    "hits" : [
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "N0WXnn4Bcy_gZ0X44pp1",
        "_score" : 1.0,
        "_source" : {
          "cds" : 0,
          "rtype" : "X",
          "sname" : "",
          tgcode"dname" : "",
          "cname" : "",
          "enroll12" : 492835,
          "NumTstTakr" : 214262,
          "AvgScrRead" : 484,
          "AvgScrMath" : 494,
          "AvgScrWrit" : 477,
          "NumGE1500" : 89840,
          "PctGE1500" : 41.93,
          "year" : 1516
        }
      },
   ...

使用 Painless 来搜索 Elasticsearch

现在我们已经将 SAT 分数加载到 “sat” 索引中,我们可以开始在 SAT 查询中使用 Painless。 在以下示例中,所有变量都将使用 def 来演示 Painless 的动态类型支持。

Elasticsearch 中的脚本格式类似于以下内容:

GET sat/_search?filter_path=**.hits
{
  "script_fields": {
    "some_scores": {
      "script": {
        "lang": "painless",
        "source": "def scores = 0; scores = doc['AvgScrRead'].value + doc['AvgScrWrit'].value; return scores;"
      }
    }
  }
}

在脚本中,你可以定义脚本语言语言,其中 Painless 是默认语言。 另外,我们可以指定脚本的 source。 我们还可以选择使用存储,它们是存储在集群中的脚本。 此外,我们还有文件脚本,它们是存储在文件中并在 Elasticsearch 的配置目录中引用的脚本。

上面的脚本都写作一行,其实可读性不是很高。我们可以使用如下的格式:

GET sat/_search?filter_path=**.hits
{
  "script_fields": {
    "some_scores": {
      "script": {
        "lang": "painless",
        "source": """
          def scores = 0; 
          scores = doc['AvgScrRead'].value + doc['AvgScrWrit'].value; 
          return scores;
        """
      }
    }
  }
}

显然这种格式跟他容易让人读。

让我们更详细地看一下上面的脚本。

在上面的脚本中,我们使用了 _search API 和 script_fields 命令。 此命令将允许我们创建一个新字段,该字段将tgcode保存我们在脚本中编写的分数。 在这里,我们将其称为 some_scores 只是作为示例。

def scores = 0;  
scores = doc['AvgScrRead'].value + doc['AvgScrWrit'].value;  
return scores;  

让我们看看结果:

{
  "hits" : {
    "hits" : [
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "N0WXnn4Bcy_gZ0X44pp1",
        "_score" : 1.0,
        "fields" : {
          "some_scores" : [
            961
          ]
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "OEWXnn4Bcy_gZ0X44pp1",
        "_score" : 1.0,
        "fields" : {
          "some_scores" : [
            1032
          ]
        }
      },
   ...

该脚本在索引中的每个文档上运行。 上面的结果表明,已经创建了一个名为 fields 的新字段,其中另一个字段包含我们使用 script_fields 命令创建的新字段 some_scores 的名称。

让我们编写另一个查询来搜索 SAT 阅读分数低于 350 且数学分数高于 350 的学校。脚本如下所示:

doc['AvgScrRead'].value  350

和查询:

GET sat/_search?filter_path=**.hits
{
  "query": {
    "script": {
      "script": {
        "lang": "painless",
        "source": """
          doc['AvgScrRead'].value  350
        """
      }
    }
  }
}

上面执行的结果为:

{
  "hits" : {
    "hits" : [
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "70WXnn4Bcy_gZ0X44pp2",
        "_score" : 1.0,
        "_source" : {
          "cds" : 7617960733659,
          "rtype" : "S",
          "sname" : "John F. Kennedy High",
          "dname" : "West Contra Costa Unified",
          "cname" : "Contra Costa",
          "enroll12" : 175,
          "NumTstTakr" : 128,
          "AvgScrRead" : 349,
          "AvgScrMath" : 352,
          "AvgScrWrit" : 345,
          "NumGE1500" : 5,
          "PctGE1500" : 3.91,
          "year" : 1516
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "90WXnn4Bcy_gZ0X44px3",
        "_score" : 1.0,
        "_source" : {
          "cds" : 19647330126508,
          "rtype" : "S",
          "sname" : "Augustus F. Hawkins High C Responsible Indigenous",
          "dname" : "Los Angeles Unified",
          "cname" : "Los Angeles",
          "enroll12" : 108,
          "NumTstTakr" : 66,
          tgcode"AvgScrRead" : 349,
          "AvgScrMath" : 353,
          "AvgScrWrit" : 338,
          "NumGE1500" : 1,
          "PctGE1500" : 1.52,
          "year" : 1516
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "DEWXnn4Bcy_gZ0X44qF4",
        "_score" : 1.0,
        "_source" : {
          "cds" : 38684780119875,
          "rtype" : "S",
          "sname" : "S.F. International High",
          "dname" : "San Francisco Unified",
          "cname" : "San Francisco",
          "enroll12" : 73,
          "NumTstTakr" : 56,
          "AvgScrRead" : 326,
          "AvgScrMath" : 368,
          "AvgScrWrit" : 311,
          "NumGE1500" : 3,
          "PctGE1500" : 5.36,
          "year" : 1516
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "FkWXnn4Bcy_gZ0X44qF4",
        "_score" : 1.0,
        "_source" : {
          "cds" : 38684783830403,
          "rtype" : "S",
          "sname" : "Marshall (Thurgood) High",
          "dname" : "San Francisco Unified",
          "cname" : "San Francisco",
          "enroll12" : 139,
          "NumTstTakr" : 66,
          "AvgScrRead" : 347,
          "AvgScrMath" : 447,
          "AvgScrWrit" : 350,
          "NumGE1500" : 3,
          "PctGE1500" : 4.55,
          "year" : 1516
        }
      }
    ]
  }
}

这将给我们四所学校。 在这四所学校中,我们可以使用 Painless 创建一个包含四个值的数组:来自我们数据的 SAT 分数和总 SAT 分数,或所有 SAT 分数的总和:

def sat_scores = [];  
def score_names = ['AvgScrRead', 'AvgScrWrit', 'AvgScrMath'];  
for (int i = 0; i 

我们将创建一个 sat_scores 数组来保存 SAT 分数(AvgScrRead、AvgScrWrit 和 AvgScrMath)以及我们将计算的总分。 我们将创建另一个名为 scores_names 的数组来保存包含 SAT 分数的文档字段的名称。 如果将来我们的字段名称发生变化,我们所要做的就是更新数组中的名称。 使用 for 循环,我们将使用 score_names 数组遍历文档字段,并将它们对应的值放入 sat_scores 数组。 接下来,我们将遍历 sat_scores 数组并将三个 SAT 分数的值相加,并将该分数放在临时变量 temp 中。 然后,我们将 temp 值添加到 sat_scores 数组中,得到三个单独的 SAT 分数加上他们的总分。

获取四所学校和脚本的整个查询如下所示:

GET sat/_search?filter_path=**.hits
{
  "query": {
    "script": {
      "script": {
        "lang": "painless",
        "source": """
            doc['AvgScrRead'].value  350
          """
      }
    }
  },
  "script_fields": {
    "scores": {
      "script": {
        "lang": "painless",
        "source": """
          def sat_scores = []; 
          def scores = ['AvgScrRead', 'AvgScrWrit', 'AvgScrMath']; 
          for (int i = 0; i 

查询返回的每个文档将类似于:

{
  "hits" : {
    "hits" : [
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "70WXnn4Bcy_gZ0X44pp2",
        "_score" : 1.0,
        "fields" : {
          "scores" : [
            349,
            345,
            352,
            1046
          ]
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "90WXnn4Bcy_gZ0X44px3",
        "_score" : 1.0,
        "fields" : {
          "scores" : [
            349,
            338,
            353,
            1040
          ]
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "DEWXnn4Bcy_gZ0X44qF4",
        "_score" : 1.0,
        "fields" : {
          "scores" : [
            326,
            311,
            368,
            1005
          ]
        }
      },
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "FkWXnn4Bcy_gZ0X44qF4",
        "_score" : 1.0,
        "fields" : {
          "scores" : [
            347,
            350,
            447,
            1144
          ]
        }
      }
    ]
  }
}

使用 _search API 的一个缺点是不存储结果。 为此,我们必须使用 _update 或 _update_by_query API 来更新单个文档或索引中的所有文档。 所以,让我们用刚刚使用的查询结果更新我们的索引。

使用 Painless 来更新 Elasticsearch 文档

在我们进一步之前,让我们在数据中创建另一个字段,该字段将保存 SAT 分数的数组。 为此,我们将使用 Elasticsearch 的 _update_by_query API 添加一个名为 All_Scores 的新字段,该字段最初将作为一个空数组开始:

POST sat/_update_by_query
{
  "script": {
    "lang": "painless",
    "source": "ctx._source.All_Scores = []"
  }
}

这将更新索引以包含我们可以开始添加分数的新字段。 为此,我们将使用脚本来更新 All_Scores 字段:

def scores = ['AvgScrRead', 'AvgScrWrit', 'AvgScrMath'];  
for (int i = 0; i 

请注意在这个时候,我们需要使用 ctx 来访问字段,而不是像之前的 doc。这里涉及到 Painless 的上下文。具体是使用哪种格式,请参阅官方文档 “Painless contexts”。

使用 _update 或 _update_by_query API,我们将无法访问 doc 值。 相反,Elasticsearch 公开了 ctx 变量和 _source 文档,允许我们访问每个文档的字段。 从那里我们可以使用每个 SAT 分数和学校的总平均 SAT 分数更新每个文档的 All_Scores 数组。

整个查询如下所示:

POST sat/_update_by_query
{
  "script": {
    "lang": "painless",
    "source": """
      def scores = ['AvgScrRead', 'AvgScrWrit', 'AvgScrMath']; 
      for (int i = 0; i 

经过上面的 update 后的文档现在变成了:

GET sat/_search?filter_path=**.hits
{
  "hits" : {
    "hits" : [
      {
        "_index" : "sat",
        "_type" : "_doc",
        "_id" : "N0WXnn4Bcy_gZ0X44pp1",
        "_score" : 1.0,
        "_source" : {
          "All_Scores" : [
            484,
            477,
            494,
            1455
          ],
          "year" : 1516,
          "cname" : "",
          "AvgScrRead" : 484,
          "rtype" : "X",
          "AvgScrMath" : 494,
          "cds" : 0,
          "sname" : "",
          "PctGE1500" : 41.93,
          "AvgScrWrit" : 477,
          "NumTstTakr" : 214262,
          "dname" : "",
          "enroll12" : 492835,
          "NumGE1500" : 89840
        }
      },
     ...

如果我们只想更新一个文档,我们也可以使用类似的脚本来完成。 我们只需要在 POST URL 中指明文档的 _id。 在接下来的更新中,我们只是将 id 为 “AV2mluV4aqbKx_m2Ul0m” 的文档的 AvgScrMath 分数加了 10 分。

POST sat/scores/AV2mluV4aqbKx_m2Ul0m/_update
{
  "script": {
    "lang": "painless",
    "source": "ctx._source.AvgScrMath += 10"
  }
}

总结

我们已经了解了 Elasticsearch 的 Painless 脚本语言的基础知识,并给出了一些关于它如何工作的示例。 此外,使用一些 Painless API 方法(如 HashMap 和循环),我们让你体验了在更新文档时可以使用该语言做什么,或者只是在返回搜索结果之前修改数据。 尽管如此,这只是 Painless 的冰山一角。

文章来源于互联网:Elasticsearch:如何在 Elasticsearch 中轻松编写 Painless 脚本

相关推荐: Kibana:构建自定义 kibana 可视化,推动更深入的洞察

截止目前为止 Kibana 已经提供了丰富的可视化工具让我们对数据进行可视化。从 Kibana 的发展史中可以看出来 Kibana 在可视化路径中的演化: 特别是最近推出的 Lens。它把创建可视化的门槛降到了极低的一个程度。它使很多不懂得 Kibana 操作…

Tags: , , ,