ES|QL 命令

ES|QL 源命令生成一个表格，通常包含来自 Elasticsearch 的数据。ES|QL 查询必须以源命令开始。

ES|QL 支持以下源命令

ES|QL 处理命令通过添加、删除或更改行和列来更改输入表格。

ES|QL 支持以下处理命令

FROM 源命令返回一个包含来自数据流、索引或别名的数据的表格。

语法

FROM index_pattern [METADATA fields]

参数

描述

FROM 源命令返回一个包含来自数据流、索引或别名的数据的表格。结果表中的每一行代表一个文档。每一列对应一个字段，并且可以通过该字段的名称访问。

FROM employees

FROM employees
| LIMIT 1000

示例

FROM employees

您可以使用日期数学来引用索引、别名和数据流。这对于时间序列数据很有用，例如访问今天的索引

FROM <logs-{now/d}>

使用逗号分隔的列表或通配符来查询多个数据流、索引或别名

FROM employees-00001,other-employees-*

使用 <remote_cluster_name>:<target> 格式来查询远程集群上的数据流和索引

FROM cluster_one:employees-00001,cluster_two:other-employees-*

使用可选的 METADATA 指令来启用元数据字段

FROM employees METADATA _id

使用双引号 (") 或三个双引号 (""") 来转义包含特殊字符的索引名称

FROM "this=that", """this[that"""

ROW 源命令生成一个包含您指定的一个或多个带值的列的行。这对于测试非常有用。

语法

ROW column1 = value1[, ..., columnN = valueN]

参数

示例

ROW a = 1, b = "two", c = null

使用方括号创建多值列

ROW a = [2, 1]

ROW 支持使用函数

ROW a = ROUND(1.23, 0)

SHOW 源命令返回有关部署及其功能的信息。

语法

SHOW item

参数

示例

使用 SHOW INFO 返回部署的版本、构建日期和哈希值。

SHOW INFO

DISSECT 使您能够从字符串中提取结构化数据。

语法

DISSECT input "pattern" [APPEND_SEPARATOR="<separator>"]

参数

描述

DISSECT 使您能够从字符串中提取结构化数据。DISSECT 将字符串与基于分隔符的模式进行匹配，并将指定的键提取为列。

有关 dissect 模式的语法，请参阅使用 DISSECT 处理数据。

示例

以下示例解析包含时间戳、一些文本和一个 IP 地址的字符串

ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1"
| DISSECT a """%{date} - %{msg} - %{ip}"""
| KEEP date, msg, ip

默认情况下，DISSECT 输出关键字字符串列。要转换为其他类型，请使用类型转换函数

ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1"
| DISSECT a """%{date} - %{msg} - %{ip}"""
| KEEP date, msg, ip
| EVAL date = TO_DATETIME(date)

DROP 处理命令删除一个或多个列。

语法

DROP columns

参数

示例

FROM employees
| DROP height

您可以使用通配符删除名称与模式匹配的所有列，而不是按名称指定每一列

FROM employees
| DROP height*

ENRICH 使您能够使用充实策略将现有索引中的数据添加为新列。

语法

ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...]

参数

描述

ENRICH 使您能够使用充实策略将现有索引中的数据添加为新列。有关设置策略的信息，请参阅数据充实。

示例

以下示例使用 languages_policy 充实策略来为策略中定义的每个充实字段添加一个新列。匹配是使用充实策略中定义的 match_field 执行的，并且要求输入表具有一个与其名称相同的列（本示例中为 language_code）。ENRICH 将根据匹配字段值在充实索引中查找记录。

ROW language_code = "1"
| ENRICH languages_policy

要使用与策略中定义的 match_field 名称不同的列作为匹配字段，请使用 ON <column-name>

ROW a = "1"
| ENRICH languages_policy ON a

默认情况下，策略中定义的每个充实字段都将添加为一列。要显式选择要添加的充实字段，请使用 WITH <field1>, <field2>, ...

ROW a = "1"
| ENRICH languages_policy ON a WITH language_name

您可以使用 WITH new_name=<field1> 重命名添加的列

ROW a = "1"
| ENRICH languages_policy ON a WITH name = language_name

如果发生名称冲突，新创建的列将覆盖现有列。

EVAL 处理命令使您能够追加具有计算值的新列。

语法

EVAL [column1 =] value1[, ..., [columnN =] valueN]

参数

描述

EVAL 处理命令使您能够追加具有计算值的新列。EVAL 支持用于计算值的各种函数。有关更多信息，请参阅函数。

示例

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height_feet = height * 3.281, height_cm = height * 100

如果指定的列已存在，则会删除现有列，并将新列附加到表中

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height = height * 3.281

指定输出列名是可选的。如果未指定，则新列名等于表达式。以下查询添加一个名为 height*3.281 的列

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height * 3.281

由于此名称包含特殊字符，因此在后续命令中使用时需要用反引号 (`) 引起来

FROM employees
| EVAL height * 3.281
| STATS avg_height_feet = AVG(`height * 3.281`)

GROK 使您能够从字符串中提取结构化数据。

语法

GROK input "pattern"

参数

描述

GROK 使您能够从字符串中提取结构化数据。GROK 基于正则表达式将字符串与模式匹配，并将指定的模式提取为列。

有关 grok 模式的语法，请参阅使用 GROK 处理数据。

示例

以下示例解析包含时间戳、IP 地址、电子邮件地址和数字的字符串

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 [email protected] 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num}"""
| KEEP date, ip, email, num

默认情况下，GROK 输出关键字字符串列。int 和 float 类型可以通过在模式中的语义后面附加 :type 来进行转换。例如 {NUMBER:num:int}

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 [email protected] 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"""
| KEEP date, ip, email, num

对于其他类型转换，请使用类型转换函数

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 [email protected] 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"""
| KEEP date, ip, email, num
| EVAL date = TO_DATETIME(date)

如果一个字段名称被多次使用，GROK 会创建一个多值列

FROM addresses
| KEEP city.name, zip_code
| GROK zip_code """%{WORD:zip_parts} %{WORD:zip_parts}"""

KEEP 处理命令允许您指定要返回的列以及返回的顺序。

语法

KEEP columns

参数

描述

KEEP 处理命令允许您指定要返回的列以及返回的顺序。

当一个字段名称与多个表达式匹配时，将应用优先级规则。字段按照它们出现的顺序添加。如果一个字段与多个表达式匹配，则应用以下优先级规则（从最高到最低优先级）：

如果一个字段与两个具有相同优先级的表达式匹配，则最右边的表达式胜出。

有关这些优先级规则的说明，请参阅示例。

示例

列将按指定的顺序返回

FROM employees
| KEEP emp_no, first_name, last_name, height

您可以使用通配符返回所有名称与模式匹配的列，而无需按名称指定每个列

FROM employees
| KEEP h*

星号通配符 (*) 本身转换为所有与其它参数不匹配的列。

此查询将首先返回所有名称以 h 开头的列，然后返回所有其他列

FROM employees
| KEEP h*, *

以下示例显示当一个字段名称与多个表达式匹配时，优先级规则如何工作。

完整字段名称的优先级高于通配符表达式

FROM employees
| KEEP first_name, last_name, first_name*

通配符表达式具有相同的优先级，但最后一个胜出（尽管不太具体）

FROM employees
| KEEP first_name*, last_name, first_na*

简单的通配符表达式 * 具有最低优先级。输出顺序由其他参数确定

FROM employees
| KEEP *, first_name

LIMIT 处理命令允许您限制返回的行数。

语法

LIMIT max_number_of_rows

参数

描述

LIMIT 处理命令允许您限制返回的行数。无论 LIMIT 命令的值如何，查询返回的行数都不会超过 10,000 行。

此限制仅适用于查询检索的行数。查询和聚合在完整数据集上运行。

要克服此限制

可以使用以下动态集群设置更改默认限制和最大限制

示例

FROM employees
| SORT emp_no ASC
| LIMIT 5

MV_EXPAND 处理命令将多值列展开为每值一行，复制其他列。

语法

MV_EXPAND column

参数

示例

ROW a=[1,2,3], b="b", j=["a","b"]
| MV_EXPAND a

RENAME 处理命令重命名一个或多个列。

语法

RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN]

参数

描述

RENAME 处理命令重命名一个或多个列。如果已存在具有新名称的列，则它将被新列替换。

示例

FROM employees
| KEEP first_name, last_name, still_hired
| RENAME  still_hired AS employed

可以使用单个 RENAME 命令重命名多个列

FROM employees
| KEEP first_name, last_name
| RENAME first_name AS fn, last_name AS ln

SORT 处理命令根据一个或多个列对表进行排序。

语法

SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]]

参数

描述

SORT 处理命令根据一个或多个列对表进行排序。

默认排序顺序为升序。使用 ASC 或 DESC 指定显式排序顺序。

具有相同排序键的两行被认为是相等的。您可以提供额外的排序表达式来作为平局打破器。

在多值列上排序时，升序排序时使用最小值，降序排序时使用最大值。

默认情况下，null 值被视为大于任何其他值。使用升序排序顺序，null 值将排在最后，而使用降序排序顺序，null 值将排在最前面。您可以通过提供 NULLS FIRST 或 NULLS LAST 来更改此行为。

示例

FROM employees
| KEEP first_name, last_name, height
| SORT height

使用 ASC 显式按升序排序

FROM employees
| KEEP first_name, last_name, height
| SORT height DESC

提供额外的排序表达式来作为平局打破器

FROM employees
| KEEP first_name, last_name, height
| SORT height DESC, first_name ASC

使用 NULLS FIRST 首先排序 null 值

FROM employees
| KEEP first_name, last_name, height
| SORT first_name ASC NULLS FIRST

STATS 处理命令根据公共值对行进行分组，并计算分组行的一个或多个聚合值。

语法

STATS [column1 =] expression1 [WHERE boolean_expression1][,
      ...,
      [columnN =] expressionN [WHERE boolean_expressionN]]
      [BY grouping_expression1[, ..., grouping_expressionN]]

参数

描述

STATS 处理命令根据公共值对行进行分组，并计算分组行的一个或多个聚合值。对于每个聚合值的计算，可以使用 WHERE 过滤组中的行。如果省略 BY，则输出表将只包含一行，其中包含应用于整个数据集的聚合。

支持以下聚合函数

支持以下分组函数

示例

计算统计信息并按另一列的值进行分组

FROM employees
| STATS count = COUNT(emp_no) BY languages
| SORT languages

省略 BY 将返回一行，其中包含应用于整个数据集的聚合

FROM employees
| STATS avg_lang = AVG(languages)

可以计算多个值

FROM employees
| STATS avg_lang = AVG(languages), max_lang = MAX(languages)

要筛选进入聚合的行，请使用 WHERE 子句

FROM employees
| STATS avg50s = AVG(salary)::LONG WHERE birth_date < "1960-01-01",
        avg60s = AVG(salary)::LONG WHERE birth_date >= "1960-01-01"
        BY gender
| SORT gender

聚合可以混合使用，可以有或没有过滤器，并且分组也是可选的

FROM employees
| EVAL Ks = salary / 1000 // thousands
| STATS under_40K = COUNT(*) WHERE Ks < 40,
        inbetween = COUNT(*) WHERE 40 <= Ks AND Ks < 60,
        over_60K  = COUNT(*) WHERE 60 <= Ks,
        total     = COUNT(*)

如果分组键是多值的，则输入行在所有组中

ROW i=1, a=["a", "b"] | STATS MIN(i) BY a | SORT a ASC

也可以按多个值进行分组

FROM employees
| EVAL hired = DATE_FORMAT("yyyy", hire_date)
| STATS avg_salary = AVG(salary) BY hired, languages.long
| EVAL avg_salary = ROUND(avg_salary)
| SORT hired, languages.long

如果所有分组键都是多值的，则输入行会出现在所有组中

ROW i=1, a=["a", "b"], b=[2, 3] | STATS MIN(i) BY a, b | SORT a ASC, b ASC

聚合函数和分组表达式都接受其他函数。这对于在多值列上使用 STATS 非常有用。例如，要计算平均工资变化，可以使用 MV_AVG 先计算每位员工的多个值的平均值，然后将结果与 AVG 函数一起使用

FROM employees
| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10)

按表达式分组的一个示例是按员工姓氏的首字母对员工进行分组

FROM employees
| STATS my_count = COUNT() BY LEFT(last_name, 1)
| SORT `LEFT(last_name, 1)`

指定输出列名是可选的。如果未指定，则新列名与表达式相同。以下查询返回一个名为 AVG(salary) 的列

FROM employees
| STATS AVG(salary)

由于此名称包含特殊字符，因此在后续命令中使用时需要用反引号 (`) 引起来

FROM employees
| STATS AVG(salary)
| EVAL avg_salary_rounded = ROUND(`AVG(salary)`)

WHERE 处理命令生成一个表，其中包含输入表中所有满足所提供条件的行的记录。

语法

WHERE expression

参数

示例

FROM employees
| KEEP first_name, last_name, still_hired
| WHERE still_hired == true

如果 still_hired 是一个布尔字段，则可以简化为

FROM employees
| KEEP first_name, last_name, still_hired
| WHERE still_hired

使用日期数学从特定时间范围检索数据。例如，要检索最近一小时的日志

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour

WHERE 支持各种函数。例如，LENGTH 函数

FROM employees
| KEEP first_name, last_name, height
| WHERE LENGTH(first_name) < 4

有关所有函数的完整列表，请参阅函数概述。

对于 NULL 比较，请使用 IS NULL 和 IS NOT NULL 谓词

FROM employees
| WHERE birth_date IS NULL
| KEEP first_name, last_name
| SORT first_name
| LIMIT 3

FROM employees
| WHERE is_rehired IS NOT NULL
| STATS COUNT(emp_no)

使用 LIKE 通过通配符根据字符串模式筛选数据。LIKE 通常作用于运算符左侧的字段，但也可以作用于常量（字面量）表达式。运算符的右侧表示模式。

支持以下通配符

支持的类型

FROM employees
| WHERE first_name LIKE """?b*"""
| KEEP first_name, last_name

匹配 * 和 . 等确切字符将需要转义。转义字符是反斜杠 \。由于反斜杠也是字符串字面量中的特殊字符，因此需要进一步转义。

ROW message = "foo * bar"
| WHERE message LIKE "foo \\* bar"

为了减少转义的开销，我们建议使用三引号字符串 """

ROW message = "foo * bar"
| WHERE message LIKE """foo \* bar"""

使用 RLIKE 通过 正则表达式根据字符串模式筛选数据。RLIKE 通常作用于运算符左侧的字段，但也可以作用于常量（字面量）表达式。运算符的右侧表示模式。

支持的类型

FROM employees
| WHERE first_name RLIKE """.leja.*"""
| KEEP first_name, last_name

匹配特殊字符（例如 ., *, (…​）将需要转义。转义字符是反斜杠 \。由于反斜杠也是字符串字面量中的特殊字符，因此需要进一步转义。

ROW message = "foo ( bar"
| WHERE message RLIKE "foo \\( bar"

为了减少转义的开销，我们建议使用三引号字符串 """

ROW message = "foo ( bar"
| WHERE message RLIKE """foo \( bar"""

IN 运算符允许测试字段或表达式是否等于字面量、字段或表达式列表中的一个元素

ROW a = 1, b = 4, c = 3
| WHERE c-a IN (3, b / 2, a)

有关所有运算符的完整列表，请参阅运算符。