« ES|QL 命令 ES|QL 元数据字段 »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›ES|QL ›ES|QL 参考

ES|QL 函数和运算符

编辑

ES|QL 函数和运算符编辑

ES|QL 提供了一套全面的函数和运算符，用于处理数据。参考文档分为以下类别

函数概述编辑

聚合函数
分组函数
条件函数和表达式
日期和时间函数
IP 函数
数学函数
空间函数
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_INTERSECTS
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_DISJOINT
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_CONTAINS
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_WITHIN
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_X
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_Y
字符串函数
类型转换函数
多值函数

运算符概述编辑

运算符

ES|QL 聚合函数编辑

STATS ... BY 命令支持以下聚合函数

AVG编辑

语法

AVG(expression)
表达式
数字表达式。

描述

数字表达式的平均值。

支持的类型

无论输入类型如何，结果始终为 double。

示例

FROM employees
| STATS AVG(height)
AVG(height):double

1.7682

表达式可以使用内联函数。例如，要计算多值列的平均值，首先使用 MV_AVG 对每行的多个值求平均值，然后将结果与 AVG 函数一起使用

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

1.3904535865

COUNT编辑

语法

COUNT([expression])

参数

表达式
输出要计数的值的表达式。如果省略，则等效于 COUNT(*)（行数）。

描述

返回输入值的总数（计数）。

支持的类型

可以接受任何字段类型作为输入。

示例

FROM employees
| STATS COUNT(height)
COUNT(height):long

100

要计算行数，请使用 COUNT() 或 COUNT(*)

FROM employees
| STATS count = COUNT(*) BY languages
| SORT languages DESC
count:long languages:integer

10

null

21

5

18

4

17

3

19

2

15

1

表达式可以使用内联函数。此示例使用 SPLIT 函数将字符串拆分为多个值，并计算这些值

ROW words="foo;bar;baz;qux;quux;foo"
| STATS word_count = COUNT(SPLIT(words, ";"))
word_count:long

6

COUNT_DISTINCT编辑

语法

COUNT_DISTINCT(expression[, precision_threshold])

参数

表达式
输出要执行唯一计数的值的表达式。
precision_threshold
精度阈值。请参阅 计数是近似的。支持的最大值为 40000。高于此数字的阈值将与阈值为 40000 的效果相同。默认值为 3000。

描述

返回唯一值的近似数量。

支持的类型

可以接受任何字段类型作为输入。

示例

FROM hosts
| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1)
COUNT_DISTINCT(ip0):long COUNT_DISTINCT(ip1):long

7

8

使用可选的第二个参数来配置精度阈值

FROM hosts
| STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5)
COUNT_DISTINCT(ip0, 80000):long COUNT_DISTINCT(ip1, 5):long

7

9

表达式可以使用内联函数。此示例使用 SPLIT 函数将字符串拆分为多个值，并计算唯一值

ROW words="foo;bar;baz;qux;quux;foo"
| STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";"))
distinct_word_count:long

5

计数是近似的编辑

计算精确计数需要将值加载到集合中并返回其大小。当处理高基数集合和/或大值时，这无法扩展，因为所需的内存使用量以及在节点之间通信这些每个分片的集合将使用集群的太多资源。

此 COUNT_DISTINCT 函数基于 HyperLogLog++ 算法，该算法基于值的哈希值进行计数，具有一些有趣的属性

  • 可配置的精度，它决定如何权衡内存和准确性，
  • 在低基数集合上具有极佳的准确性，
  • 固定的内存使用量：无论是否有数十亿个唯一值，内存使用量仅取决于配置的精度。

对于精度阈值为 c，我们正在使用的实现大约需要 c * 8 字节。

下图显示了阈值前后误差的变化情况

cardinality error

对于所有 3 个阈值，计数在配置的阈值内一直是准确的。虽然不能保证，但这很可能是这种情况。实际中的准确性取决于所讨论的数据集。一般来说，大多数数据集都显示出始终如一的良好准确性。还要注意，即使阈值低至 100，即使计数数百万个项目，误差仍然非常低（如上图所示，为 1-6%）。

HyperLogLog++ 算法依赖于哈希值的领先零，数据集中的哈希值的精确分布会影响基数的准确性。

COUNT_DISTINCT 函数接受一个可选的第二个参数来配置精度阈值。precision_threshold 选项允许在内存和精度之间进行权衡，并定义一个唯一的计数，低于该计数，预计计数将接近准确。高于此值，计数可能会变得更加模糊。支持的最大值为 40000，高于此值的阈值将与阈值为 40000 的效果相同。默认值为 3000。

MAX编辑

语法

MAX(expression)

参数

表达式
要返回最大值的表达式。

描述

返回数值表达式的最大值。

示例

FROM employees
| STATS MAX(languages)
MAX(languages):integer

5

表达式可以使用内联函数。例如，要计算多值列平均值的最大值，请使用 MV_AVG 先对每行的多个值求平均值，然后将结果与 MAX 函数一起使用

FROM employees
| STATS max_avg_salary_change = MAX(MV_AVG(salary_change))
max_avg_salary_change:double

13.75

MEDIAN编辑

语法

MEDIAN(expression)

参数

表达式
要返回中位数的表达式。

描述

返回大于一半值且小于一半值的数值，也称为 50% PERCENTILE。

与 PERCENTILE 一样，MEDIAN 通常是近似的。

MEDIAN 也是非确定性的。这意味着使用相同的数据可能会得到略微不同的结果。

示例

FROM employees
| STATS MEDIAN(salary), PERCENTILE(salary, 50)
MEDIAN(salary):double PERCENTILE(salary, 50):double

47003

47003

表达式可以使用内联函数。例如，要计算多值列的最大值的中间值，请先使用 MV_MAX 获取每行的最大值，然后将结果与 MEDIAN 函数一起使用

FROM employees
| STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change))
median_max_salary_change:double

7.69

MEDIAN_ABSOLUTE_DEVIATION编辑

语法

MEDIAN_ABSOLUTE_DEVIATION(expression)

参数

表达式
要返回中位数绝对偏差的表达式。

描述

返回中位数绝对偏差，这是变异性的度量。它是一个稳健的统计量，这意味着它对于描述可能存在异常值或可能不符合正态分布的数据很有用。对于此类数据，它可能比标准差更具描述性。

它是通过计算每个数据点与整个样本中位数的偏差的中位数来计算的。也就是说，对于一个随机变量 X，中位数绝对偏差是 median(|median(X) - X|)。

与 PERCENTILE 一样，MEDIAN_ABSOLUTE_DEVIATION 通常是近似的。

MEDIAN_ABSOLUTE_DEVIATION 也是非确定性的。这意味着使用相同的数据可能会得到略微不同的结果。

示例

FROM employees
| STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary)
MEDIAN(salary):double MEDIAN_ABSOLUTE_DEVIATION(salary):double

47003

10096.5

表达式可以使用内联函数。例如，要计算多值列的最大值的中间值绝对偏差，请先使用 MV_MAX 获取每行的最大值，然后将结果与 MEDIAN_ABSOLUTE_DEVIATION 函数一起使用

FROM employees
| STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change))
m_a_d_max_salary_change:double

5.69

MIN编辑

语法

MIN(expression)

参数

表达式
要返回最小值的表达式。

描述

返回数值表达式的最小值。

示例

FROM employees
| STATS MIN(languages)
MIN(languages):integer

1

表达式可以使用内联函数。例如，要计算多值列平均值的最小值，请使用 MV_AVG 先对每行的多个值求平均值，然后将结果与 MIN 函数一起使用

FROM employees
| STATS min_avg_salary_change = MIN(MV_AVG(salary_change))
min_avg_salary_change:double

-8.46

PERCENTILE编辑

语法

PERCENTILE(expression, percentile)

参数

表达式
要返回百分位的表达式。
百分位数
一个常数数值表达式。

描述

返回观察值出现一定百分比的值。例如，第 95 个百分位数是大于 95% 观察值的值，第 50 个百分位数是 MEDIAN。

示例

FROM employees
| STATS p0 = PERCENTILE(salary,  0)
     , p50 = PERCENTILE(salary, 50)
     , p99 = PERCENTILE(salary, 99)
p0:double p50:double p99:double

25324

47003

74970.29

表达式可以使用内联函数。例如，要计算多值列的最大值的百分位数，请先使用 MV_MAX 获取每行的最大值，然后将结果与 PERCENTILE 函数一起使用

FROM employees
| STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80)
p80_max_salary_change:double

12.132

PERCENTILE 通常是近似的编辑

有许多不同的算法来计算百分位数。朴素的实现只是将所有值存储在一个排序数组中。要找到第 50 个百分位数，您只需找到位于 my_array[count(my_array) * 0.5] 的值。

显然，朴素的实现无法扩展——排序数组随着数据集中的值数量线性增长。为了在 Elasticsearch 集群中跨数十亿个值计算百分位数，计算近似百分位数。

percentile 指标使用的算法称为 TDigest（由 Ted Dunning 在 使用 T-Digests 计算准确的分位数 中介绍）。

使用此指标时，请牢记以下几点准则

  • 精度与 q(1-q) 成正比。这意味着极端百分位数（例如 99%）比中位数等不太极端的百分位数更准确
  • 对于少量值，百分位数非常准确（如果数据足够小，则可能 100% 准确）。
  • 随着桶中值的数量增加，该算法开始近似百分位数。它实际上是在用精度换取内存节省。不准确的精确程度很难概括，因为它取决于您的数据分布和正在聚合的数据量

下图显示了均匀分布的相对误差，具体取决于收集的值的数量和请求的百分位数

percentiles error

它显示了极端百分位数的精度如何更好。误差随着值数量的增加而减小的原因是，大数定律使值的分布越来越均匀，并且 t-digest 树可以更好地对其进行汇总。它不会发生在更偏斜的分布上。

PERCENTILE 也是非确定性的。这意味着使用相同的数据可能会得到略微不同的结果。

ST_CENTROID_AGG编辑

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

在具有空间点几何类型的字段上计算空间质心。

FROM airports
| STATS centroid=ST_CENTROID_AGG(location)
centroid:geo_point

POINT(-0.030548143003023033 24.37553649504829)

支持的类型

v result

geo_point

geo_point

cartesian_point

cartesian_point

SUM编辑

语法

SUM(expression)
表达式
数字表达式。

描述

返回数值表达式的总和。

示例

FROM employees
| STATS SUM(languages)
SUM(languages):long

281

表达式可以使用内联函数。例如，要计算每个员工的最大工资变化的总和，请将 MV_MAX 函数应用于每行，然后对结果求和

FROM employees
| STATS total_salary_changes = SUM(MV_MAX(salary_change))
total_salary_changes:double

446.75

VALUES编辑

不要在生产环境中使用 VALUES。此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

VALUES(expression)
表达式
除 geo_point、cartesian_point、geo_shape 或 cartesian_shape 之外的任何类型的表达式。

描述

将组中的所有值作为多值字段返回。返回值的顺序不保证。如果您需要按顺序返回的值，请使用 MV_SORT。

这可能会使用大量的内存，ES|QL 尚未将聚合扩展到内存之外。因此，此聚合将一直有效，直到它用于收集比内存所能容纳的更多值。一旦它收集了太多值，它将使用 断路器错误 失败查询。

示例

  FROM employees
| EVAL first_letter = SUBSTRING(first_name, 0, 1)
| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter
| SORT first_letter
first_name:keyword first_letter:keyword

[Alejandro, Amabile, Anneke, Anoosh, Arumugam]

A

[Basil, Berhard, Berni, Bezalel, Bojan, Breannda, Brendon]

B

[Charlene, Chirstian, Claudi, Cristinel]

C

[Danel, Divier, Domenick, Duangkaew]

D

[Ebbe, Eberhardt, Erez]

E

Florian

F

[Gao, Georgi, Georgy, Gino, Guoxiang]

G

[Heping, Hidefumi, Hilari, Hironobu, Hironoby, Hisao]

H

[Jayson, Jungsoon]

J

[Kazuhide, Kazuhito, Kendra, Kenroku, Kshitij, Kwee, Kyoichi]

K

[Lillian, Lucien]

L

[Magy, Margareta, Mary, Mayuko, Mayumi, Mingsen, Mokhtar, Mona, Moss]

M

Otmar

O

[Parto, Parviz, Patricio, Prasadram, Premal]

P

[Ramzi, Remzi, Reuven]

R

[Sailaja, Saniya, Sanjiv, Satosi, Shahaf, Shir, Somnath, Sreekrishna, Sudharsan, Sumant, Suzette]

S

[Tse, Tuval, Tzvetan]

T

[Udi, Uri]

U

[Valdiodio, Valter, Vishv]

V

Weiyi

W

Xinglin

X

[Yinghua, Yishay, Yongqiao]

Y

[Zhongwei, Zvonko]

Z

null

null

ES|QL 分组函数编辑

STATS ... BY 命令支持以下分组函数

BUCKETedit

语法

BUCKET(expression, buckets, from, to)

参数

字段
用于推导出桶的数值或日期表达式。
桶
目标桶数。
从
范围的开始。可以是数字或以字符串表示的日期。
到
范围的结束。可以是数字或以字符串表示的日期。

描述

创建易于理解的桶，并为每行返回一个值，该值对应于该行所属的桶。

BUCKET 可以以两种模式工作：一种是根据桶计数建议（四个参数）和范围计算桶的大小，另一种是直接提供桶的大小（两个参数）。

使用目标桶数、范围的开始和范围的结束，BUCKET 会选择合适的桶大小来生成目标桶数或更少的桶。例如，要求在一年的时间内最多有 20 个桶，就会得到按月划分的桶

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT hire_date
hire_date:date month:date

[1985-02-18T00:00:00.000Z, 1985-02-24T00:00:00.000Z]

1985-02-01T00:00:00.000Z

1985-05-13T00:00:00.000Z

1985-05-01T00:00:00.000Z

1985-07-09T00:00:00.000Z

1985-07-01T00:00:00.000Z

1985-09-17T00:00:00.000Z

1985-09-01T00:00:00.000Z

[1985-10-14T00:00:00.000Z, 1985-10-20T00:00:00.000Z]

1985-10-01T00:00:00.000Z

[1985-11-19T00:00:00.000Z, 1985-11-20T00:00:00.000Z, 1985-11-21T00:00:00.000Z]

1985-11-01T00:00:00.000Z

目标不是提供正好目标数量的桶，而是选择一个人们感觉舒适的范围，该范围最多提供目标数量的桶。

将 BUCKET 与一个聚合结合使用，可以创建一个直方图

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT month
hires_per_month:long month:date

2

1985-02-01T00:00:00.000Z

1

1985-05-01T00:00:00.000Z

1

1985-07-01T00:00:00.000Z

1

1985-09-01T00:00:00.000Z

2

1985-10-01T00:00:00.000Z

4

1985-11-01T00:00:00.000Z

BUCKET 不会创建与任何文档不匹配的桶。这就是为什么此示例缺少 1985-03-01 和其他日期的原因。

要求更多的桶可能会导致范围更小。例如，要求在一年的时间内最多有 100 个桶，就会得到按周划分的桶

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT week
hires_per_week:long week:date

2

1985-02-18T00:00:00.000Z

1

1985-05-13T00:00:00.000Z

1

1985-07-08T00:00:00.000Z

1

1985-09-16T00:00:00.000Z

2

1985-10-14T00:00:00.000Z

4

1985-11-18T00:00:00.000Z

BUCKET 不会过滤任何行。它只使用提供的范围来选择合适的桶大小。对于值在范围之外的行，它会返回一个与范围之外的桶相对应的桶值。将 BUCKET 与WHERE结合使用以过滤行。

如果预先知道所需的桶大小，只需将其作为第二个参数提供，省略范围即可

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)
| SORT week
hires_per_week:long week:date

2

1985-02-18T00:00:00.000Z

1

1985-05-13T00:00:00.000Z

1

1985-07-08T00:00:00.000Z

1

1985-09-16T00:00:00.000Z

2

1985-10-14T00:00:00.000Z

4

1985-11-18T00:00:00.000Z

当将桶大小作为第二个参数提供时，它必须是时间持续时间或日期周期。

BUCKET 也可以对数值字段进行操作。例如，要创建一个薪资直方图

FROM employees
| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999)
| SORT bs
COUNT(*):long bs:double

9

25000.0

9

30000.0

18

35000.0

11

40000.0

11

45000.0

10

50000.0

7

55000.0

9

60000.0

8

65000.0

8

70000.0

与前面的示例不同，前面的示例有意地过滤了日期范围，而您很少需要过滤数值范围。您必须分别找到 min 和 max。ES|QL 还没有简单的方法可以自动执行此操作。

如果预先知道所需的桶大小，可以省略范围。只需将其作为第二个参数提供即可

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.)
| SORT b
c:long b:double

1

25000.0

1

30000.0

1

40000.0

2

45000.0

2

50000.0

1

55000.0

1

60000.0

1

65000.0

1

70000.0

当将桶大小作为第二个参数提供时，它必须是浮点类型。

为过去 24 小时创建每小时的桶，并计算每小时的事件数

FROM sample_data
| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()
| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())

示例

为 1985 年创建按月划分的桶，并计算按招聘月份划分的平均薪资

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT bucket
AVG(salary):double bucket:date

46305.0

1985-02-01T00:00:00.000Z

44817.0

1985-05-01T00:00:00.000Z

62405.0

1985-07-01T00:00:00.000Z

49095.0

1985-09-01T00:00:00.000Z

51532.0

1985-10-01T00:00:00.000Z

54539.75

1985-11-01T00:00:00.000Z

BUCKET 可用于STATS …​ BY …​命令的聚合部分和分组部分，前提是在聚合部分中，该函数由分组部分中定义的别名引用，或者使用完全相同的表达式调用该函数

FROM employees
| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.)
| SORT b1, b2
| KEEP s1, b1, s2, b2
s1:double b1:double s2:double b2:double

351.0

350.0

1002.0

1000.0

401.0

400.0

1002.0

1000.0

451.0

450.0

1002.0

1000.0

501.0

500.0

1002.0

1000.0

551.0

550.0

1002.0

1000.0

601.0

600.0

1002.0

1000.0

601.0

600.0

1052.0

1050.0

651.0

650.0

1052.0

1050.0

701.0

700.0

1052.0

1050.0

751.0

750.0

1052.0

1050.0

801.0

800.0

1052.0

1050.0

ES|QL 条件函数和表达式edit

条件函数通过以 if-else 方式进行评估来返回其参数之一。ES|QL 支持以下条件函数

CASEedit

语法

CASE(condition1, value1[, ..., conditionN, valueN][, default_value])

参数

conditionX
条件。
valueX
当相应的条件是第一个评估为 true 的条件时返回的值。
default_value
当没有条件匹配时返回的默认值。

描述

接受条件和值的配对。该函数返回属于第一个评估为 true 的条件的值。

如果参数数量为奇数，则最后一个参数是默认值，当没有条件匹配时返回该值。如果参数数量为偶数，并且没有条件匹配，则该函数返回 null。

示例

确定员工是单语、双语还是多语

FROM employees
| EVAL type = CASE(
    languages <= 1, "monolingual",
    languages <= 2, "bilingual",
     "polyglot")
| KEEP emp_no, languages, type
emp_no:integer languages:integer type:keyword

10001

2

bilingual

10002

5

polyglot

10003

4

polyglot

10004

5

polyglot

10005

1

monolingual

根据日志消息计算总连接成功率

FROM sample_data
| EVAL successful = CASE(
    STARTS_WITH(message, "Connected to"), 1,
    message == "Connection error", 0
  )
| STATS success_rate = AVG(successful)
success_rate:double

0.5

计算每小时的错误率，作为日志消息总数的百分比

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour
error_rate:double hour:date

0.0

2023-10-23T12:00:00.000Z

0.6

2023-10-23T13:00:00.000Z

COALESCEedit

语法

COALESCE(expression1 [, ..., expressionN])

参数

first
要评估的表达式
rest
要评估的其他表达式

描述

返回其参数中第一个非空的值。如果所有参数都为空，则返回 null。

示例

ROW a=null, b="b"
| EVAL COALESCE(a, b)
a:null b:keyword COALESCE(a, b):keyword

null

b

b

GREATESTedit

语法

GREATEST(first,rest)

参数

first
要评估的第一个列。
rest
要评估的其他列。

描述

返回多个列中的最大值。这类似于 MV_MAX，但它旨在一次对多个列运行。

在 keyword 或 text 字段上运行时，这将返回按字母顺序排列的最后一个字符串。在 boolean 列上运行时，如果任何值为 true，则将返回 true。

支持的类型

first rest result

boolean

boolean

boolean

boolean

boolean

double

double

double

integer

integer

integer

integer

integer

ip

ip

ip

keyword

keyword

keyword

keyword

keyword

long

long

long

long

long

text

text

text

text

text

version

version

version

示例

ROW a = 10, b = 20
| EVAL g = GREATEST(a, b)
a:integer b:integer g:integer

10

20

20

LEASTedit

语法

LEAST(first,rest)

参数

first
要评估的第一个列。
rest
要评估的其他列。

描述

返回多个列中的最小值。这类似于 MV_MIN，但它旨在一次对多个列运行。

在 keyword 或 text 字段上运行时，这将返回按字母顺序排列的第一个字符串。在 boolean 列上运行时，如果任何值为 false，则将返回 false。

支持的类型

first rest result

boolean

boolean

boolean

boolean

boolean

double

double

double

integer

integer

integer

integer

integer

ip

ip

ip

keyword

keyword

keyword

keyword

keyword

long

long

long

long

long

text

text

text

text

text

version

version

version

示例

ROW a = 10, b = 20
| EVAL l = LEAST(a, b)
a:integer b:integer l:integer

10

20

10

ES|QL 日期时间函数edit

ES|QL 支持以下日期时间函数

DATE_DIFFedit

语法

DATE_DIFF(unit,startTimestamp,endTimestamp)

参数

单位
时间差单位。
startTimestamp
开始时间戳。
endTimestamp
结束时间戳。

描述

从 endTimestamp 中减去 startTimestamp，并以 unit 的倍数返回差值。如果 startTimestamp 晚于 endTimestamp，则返回负值。

日期时间差单位

单位

缩写

year

years, yy, yyyy

quarter

quarters, qq, q

month

months, mm, m

dayofyear

dy, y

day

days, dd, d

week

weeks, wk, ww

weekday

weekdays, dw

hour

hours, hh

minute

minutes, mi, n

second

seconds, ss, s

millisecond

milliseconds, ms

microsecond

microseconds, mcs

nanosecond

nanoseconds, ns

请注意，虽然该函数支持的单位与 ES|QL 支持的时间跨度文字之间存在重叠，但这些集合是不同的，不可互换。同样，支持的缩写与其他已建立产品中此函数的实现共享，并不一定与 Elasticsearch 使用的日期时间命名法相同。

支持的类型

单位 startTimestamp endTimestamp result

keyword

datetime

datetime

integer

text

datetime

datetime

integer

示例

ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)
date1:date date2:date dd_ms:integer

2023-12-02T11:00:00.000Z

2023-12-02T11:00:00.001Z

1000

DATE_EXTRACTedit

语法

DATE_EXTRACT(date_part, date)

参数

date_part

要提取的日期部分。可以是：aligned_day_of_week_in_month、aligned_day_of_week_in_year、aligned_week_of_month、aligned_week_of_year、ampm_of_day、clock_hour_of_ampm、clock_hour_of_day、day_of_month、day_of_week、day_of_year、epoch_day、era、hour_of_ampm、hour_of_day、instant_seconds、micro_of_day、micro_of_second、milli_of_day、milli_of_second、minute_of_day、minute_of_hour、month_of_year、nano_of_day、nano_of_second、offset_seconds、proleptic_month、second_of_day、second_of_minute、year 或 year_of_era。有关这些值的描述，请参阅 java.time.temporal.ChronoField。

如果为 null，则函数返回 null。

date
日期表达式。如果为 null，则函数返回 null。

描述

提取日期的各个部分，例如年、月、日、时。

示例

ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06")
| EVAL year = DATE_EXTRACT("year", date)
date:date year:long

2022-05-06T00:00:00.000Z

2022

查找在任何给定日期的非工作时间（上午 9 点之前或下午 5 点之后）发生的事件。

FROM sample_data
| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17
@timestamp:date client_ip:ip event_duration:long message:keyword

DATE_FORMATedit

语法

DATE_FORMAT([format,] date)

参数

format
日期格式（可选）。如果未指定格式，则使用 yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式。如果为 null，则函数返回 null。
date
日期表达式。如果为 null，则函数返回 null。

描述

以提供的格式返回日期的字符串表示形式。

示例

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL hired = DATE_FORMAT("YYYY-MM-dd", hire_date)
first_name:keyword last_name:keyword hire_date:date hired:keyword

Alejandro

McAlpine

1991-06-26T00:00:00.000Z

1991-06-26

Amabile

Gomatam

1992-11-18T00:00:00.000Z

1992-11-18

Anneke

Preusig

1989-06-02T00:00:00.000Z

1989-06-02

DATE_PARSEedit

语法

DATE_PARSE([format,] date_string)

参数

format
日期格式。有关语法，请参阅 DateTimeFormatter 文档。如果为 null，则函数返回 null。
date_string
日期表达式作为字符串。如果为 null 或空字符串，则函数返回 null。

描述

通过使用第一个参数中指定的格式解析第二个参数来返回日期。

示例

ROW date_string = "2022-05-06"
| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string)
date_string:keyword date:date

2022-05-06

2022-05-06T00:00:00.000Z

DATE_TRUNCedit

语法

DATE_TRUNC(interval,date)

参数

interval
间隔；使用时间跨度文字语法表示。
date
日期表达式

描述

将日期向下舍入到最接近的间隔。

支持的类型

interval date result

date_period

datetime

datetime

time_duration

datetime

datetime

示例

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL year_hired = DATE_TRUNC(1 year, hire_date)
first_name:keyword last_name:keyword hire_date:date year_hired:date

Alejandro

McAlpine

1991-06-26T00:00:00.000Z

1991-01-01T00:00:00.000Z

Amabile

Gomatam

1992-11-18T00:00:00.000Z

1992-01-01T00:00:00.000Z

Anneke

Preusig

1989-06-02T00:00:00.000Z

1989-01-01T00:00:00.000Z

将 DATE_TRUNC 与 STATS ... BY 结合使用以创建日期直方图。例如，每年的雇用人数

FROM employees
| EVAL year = DATE_TRUNC(1 year, hire_date)
| STATS hires = COUNT(emp_no) BY year
| SORT year
hires:long year:date

11

1985-01-01T00:00:00.000Z

11

1986-01-01T00:00:00.000Z

15

1987-01-01T00:00:00.000Z

9

1988-01-01T00:00:00.000Z

13

1989-01-01T00:00:00.000Z

12

1990-01-01T00:00:00.000Z

6

1991-01-01T00:00:00.000Z

8

1992-01-01T00:00:00.000Z

3

1993-01-01T00:00:00.000Z

4

1994-01-01T00:00:00.000Z

5

1995-01-01T00:00:00.000Z

1

1996-01-01T00:00:00.000Z

1

1997-01-01T00:00:00.000Z

1

1999-01-01T00:00:00.000Z

或每小时的错误率

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour
error_rate:double hour:date

0.0

2023-10-23T12:00:00.000Z

0.6

2023-10-23T13:00:00.000Z

NOWedit

语法

NOW()

参数

描述

返回当前日期和时间。

支持的类型

result

datetime

示例

ROW current_date = NOW()
y:keyword

20

要检索过去一小时的日志

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour
@timestamp:date client_ip:ip event_duration:long message:keyword

ES|QL IP 函数edit

ES|QL 支持以下 IP 函数

CIDR_MATCHedit

语法

CIDR_MATCH(ip, block1[, ..., blockN])

参数

ip
类型为 ip 的 IP 地址（支持 IPv4 和 IPv6）。
blockX
要测试 IP 的 CIDR 块。

描述

如果提供的 IP 包含在提供的 CIDR 块之一中，则返回 true。

示例

FROM hosts
| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32")
| KEEP card, host, ip0, ip1
card:keyword host:keyword ip0:ip ip1:ip

eth1

beta

127.0.0.1

127.0.0.2

eth0

gamma

fe80::cae2:65ff:fece:feb9

127.0.0.3

ES|QL 数学函数edit

ES|QL 支持以下数学函数

ABSedit

语法

ABS(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

返回绝对值。

支持的类型

number result

double

double

integer

integer

long

long

unsigned_long

unsigned_long

示例

ROW number = -1.0
| EVAL abs_number = ABS(number)
number:double abs_number:double

-1.0

1.0

 
FROM employees
| KEEP first_name, last_name, height
| EVAL abs_height = ABS(0.0 - height)
first_name:keyword last_name:keyword height:double abs_height:double

Alejandro

McAlpine

1.48

1.48

Amabile

Gomatam

2.09

2.09

Anneke

Preusig

1.56

1.56

ACOSedit

语法

ACOS(number)

参数

number
-1 到 1 之间的数字。如果为 null，则函数返回 null。

描述

返回 n 的 反余弦，以弧度表示的角度。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=.9
| EVAL acos=ACOS(a)
a:double acos:double

.9

0.45102681179626236

ASINedit

语法

ASIN(number)

参数

number
-1 到 1 之间的数字。如果为 null，则函数返回 null。

描述

返回输入数字表达式的 反正弦，以弧度表示的角度。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=.9
| EVAL asin=ASIN(a)
a:double asin:double

.9

1.1197695149986342

ATANedit

语法

ATAN(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

返回输入数字表达式的 反正切，以弧度表示的角度。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=12.9
| EVAL atan=ATAN(a)
a:double atan:double

12.9

1.4934316673669235

ATAN2edit

语法

ATAN2(y_coordinate,x_coordinate)

参数

y_coordinate
y 坐标。如果为 null，则函数返回 null。
x_coordinate
x 坐标。如果为 null，则函数返回 null。

描述

笛卡尔平面中从原点到点 (x , y) 的射线与正 x 轴之间的 角度，以弧度表示。

支持的类型

y_coordinate x_coordinate result

double

double

double

double

integer

double

double

long

double

double

unsigned_long

double

integer

double

double

integer

integer

double

integer

long

double

integer

unsigned_long

double

long

double

double

long

integer

double

long

long

double

long

unsigned_long

double

unsigned_long

double

double

unsigned_long

integer

double

unsigned_long

long

double

unsigned_long

unsigned_long

double

示例

ROW y=12.9, x=.6
| EVAL atan2=ATAN2(y, x)
y:double x:double atan2:double

12.9

0.6

1.5243181954438936

CEILedit

语法

CEIL(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

将数字向上舍入到最接近的整数。

对于 long（包括无符号）和 integer 来说，这是一个无操作。对于 double，这将选择最接近整数的 double 值，类似于 Math.ceil。

支持的类型

number result

double

double

integer

integer

long

long

unsigned_long

unsigned_long

示例

ROW a=1.8
| EVAL a=CEIL(a)
a:double

2

COSedit

语法

COS(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 余弦。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL cos=COS(a)
a:double cos:double

1.8

-0.2272020946930871

COSHedit

语法

COSH(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 双曲余弦。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL cosh=COSH(a)
a:double cosh:double

1.8

3.1074731763172667

Eedit

语法

E()

参数

描述

返回 欧拉数。

支持的类型

result

double

示例

ROW E()
E():double

2.718281828459045

FLOORedit

语法

FLOOR(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

将数字向下舍入到最接近的整数。

对于 long（包括无符号）和 integer 来说，这是一个无操作。对于 double，这将选择最接近整数的 double 值，类似于 Math.floor。

支持的类型

number result

double

double

integer

integer

long

long

unsigned_long

unsigned_long

示例

ROW a=1.8
| EVAL a=FLOOR(a)
a:double

1

LOGedit

语法

LOG(base,number)

参数

base
对数的底数。如果为 null，则函数返回 null。如果未提供，则此函数返回值的自然对数（以 e 为底）。
number
数字表达式。如果为 null，则函数返回 null。

描述

返回值以某个底数的对数。输入可以是任何数字值，返回值始终为 double。零、负数和底数为 1 的对数将返回 null 以及警告。

支持的类型

base number result

double

double

double

double

integer

double

double

long

double

double

unsigned_long

double

double

double

integer

double

double

integer

integer

double

integer

long

double

integer

unsigned_long

double

integer

double

long

double

double

long

integer

double

long

long

double

long

unsigned_long

double

long

double

unsigned_long

double

double

unsigned_long

integer

double

unsigned_long

long

double

unsigned_long

unsigned_long

double

unsigned_long

double

示例

ROW base = 2.0, value = 8.0
| EVAL s = LOG(base, value)
base: double value: double s:double

2.0

8.0

3.0

 
row value = 100
| EVAL s = LOG(value);
value: integer s:double

100

4.605170185988092

LOG10edit

语法

LOG10(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

返回值以 10 为底的对数。输入可以是任何数字值，返回值始终为 double。0 和负数的对数将返回 null 以及警告。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW d = 1000.0
| EVAL s = LOG10(d)
d: double s:double

1000.0

3.0

PIedit

语法

PI()

参数

描述

返回 Pi，即圆周长与其直径之比。

支持的类型

result

double

示例

ROW PI()
PI():double

3.141592653589793

POWedit

语法

POW(base,exponent)

参数

base
底数的数字表达式。如果为 null，则函数返回 null。
exponent
指数的数字表达式。如果为 null，则函数返回 null。

描述

返回 base 的 exponent 次方。

这里仍然可能导致 double 结果溢出；在这种情况下，将返回 null。

支持的类型

base exponent result

double

double

double

double

integer

double

double

long

double

double

unsigned_long

double

integer

double

double

integer

integer

double

integer

long

double

integer

unsigned_long

double

long

double

double

long

integer

double

long

long

double

long

unsigned_long

double

unsigned_long

double

double

unsigned_long

integer

double

unsigned_long

long

double

unsigned_long

unsigned_long

double

示例

ROW base = 2.0, exponent = 2
| EVAL result = POW(base, exponent)
base:double exponent:integer result:double

2.0

2

4.0

指数可以是分数，这类似于执行开方。例如，指数为 0.5 将给出底数的平方根

ROW base = 4, exponent = 0.5
| EVAL s = POW(base, exponent)
base:integer exponent:double s:double

4

0.5

2.0

ROUNDedit

语法

ROUND(number,decimals)

参数

number
要舍入的数字值。如果为 null，则函数返回 null。
decimals
要舍入的小数位数。默认为 0。如果为 null，则函数返回 null。

描述

将数字舍入到指定的位数。默认值为 0，返回最接近的整数。如果精度为负数，则舍入到小数点左侧的位数。

支持的类型

number decimals result

double

integer

double

double

double

integer

integer

integer

integer

integer

long

integer

long

long

long

unsigned_long

unsigned_long

示例

FROM employees
| KEEP first_name, last_name, height
| EVAL height_ft = ROUND(height * 3.281, 1)
first_name:keyword last_name:keyword height:double height_ft:double

Arumugam

Ossenbruggen

2.1

6.9

Kwee

Schusler

2.1

6.9

Saniya

Kalloufi

2.1

6.9

SIGNUMedit

语法

SIGNUM(number)

参数

number
数字表达式。如果为 null，则函数返回 null。

描述

返回给定数字的符号。对于负数返回 -1，对于 0 返回 0，对于正数返回 1。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW d = 100.0
| EVAL s = SIGNUM(d)
d: double s:double

100

1.0

SINedit

语法

SIN(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 正弦 三角函数。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL sin=SIN(a)
a:double sin:double

1.8

0.9738476308781951

SINHedit

语法

SINH(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 双曲正弦。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL sinh=SINH(a)
a:double sinh:double

1.8

2.94217428809568

SQRTedit

语法

SQRT(number)

参数

n
数字表达式。如果为 null，则函数返回 null。

描述

返回数字的平方根。输入可以是任何数值，返回值始终为双精度浮点数。

负数的平方根为 NaN。无穷大的平方根为无穷大。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW d = 100.0
| EVAL s = SQRT(d)
d: double s:double

100.0

10.0

TANedit

语法

TAN(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 正切 三角函数。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL tan=TAN(a)
a:double tan:double

1.8

-4.286261674628062

TANHedit

语法

TANH(angle)

参数

angle
以弧度表示的角度。如果为 null，则函数返回 null。

描述

返回角度的 双曲正切。

支持的类型

angle result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=1.8
| EVAL tanh=TANH(a)
a:double tanh:double

1.8

0.9468060128462683

TAUedit

语法

TAU()

描述

返回圆周长与其半径的 比率。

示例

ROW TAU()
TAU():double

6.283185307179586

ES|QL 空间函数edit

ES|QL 支持以下空间函数

  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_INTERSECTS
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_DISJOINT
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_CONTAINS
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_WITHIN
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_X
  • [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 ST_Y

ST_INTERSECTSedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_INTERSECTS(geomA,geomB)

参数

geomA
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。
geomB
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。第二个参数必须与第一个参数具有相同的坐标系。这意味着无法组合 geo_* 和 cartesian_* 参数。

描述

如果两个几何图形相交，则返回 true。如果它们有任何公共点，包括它们的内部点（线上的点或多边形内的点），则它们相交。这是 ST_DISJOINT 函数的逆运算。在数学术语中：ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅

支持的类型

geomA geomB result

cartesian_point

cartesian_point

boolean

cartesian_point

cartesian_shape

boolean

cartesian_shape

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

geo_point

geo_point

boolean

geo_point

geo_shape

boolean

geo_shape

geo_point

boolean

geo_shape

geo_shape

boolean

示例

FROM airports
| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))"))
abbrev:keyword city:keyword city_location:geo_point country:keyword location:geo_point name:text scalerank:i type:k

HOD

Al Ḩudaydah

POINT(42.9511 14.8022)

Yemen

POINT(42.97109630194 14.7552534413725)

Hodeidah Int’l

9

mid

ST_DISJOINTedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_DISJOINT(geomA,geomB)

参数

geomA
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。
geomB
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。第二个参数必须与第一个参数具有相同的坐标系。这意味着无法组合 geo_* 和 cartesian_* 参数。

描述

返回两个几何图形或几何图形列是否不相交。

这是 ST_INTERSECTS 函数的逆运算。在数学术语中：ST_Disjoint(A, B) ⇔ A ⋂ B = ∅

支持的类型

geomA geomB result

cartesian_point

cartesian_point

boolean

cartesian_point

cartesian_shape

boolean

cartesian_shape

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

geo_point

geo_point

boolean

geo_point

geo_shape

boolean

geo_shape

geo_point

boolean

geo_shape

geo_shape

boolean

示例

FROM airport_city_boundaries
| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))"))
| KEEP abbrev, airport, region, city, city_location
abbrev:keyword airport:text region:text city:keyword city_location:geo_point

ACA

General Juan N Alvarez Int’l

Acapulco de Juárez

Acapulco de Juárez

POINT (-99.8825 16.8636)

ST_CONTAINSedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_CONTAINS(geomA,geomB)

参数

geomA
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。
geomB
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。第二个参数必须与第一个参数具有相同的坐标系。这意味着无法组合 geo_* 和 cartesian_* 参数。

描述

返回第一个几何图形是否包含第二个几何图形。

这是 ST_WITHIN 函数的逆运算。

支持的类型

geomA geomB result

cartesian_point

cartesian_point

boolean

cartesian_point

cartesian_shape

boolean

cartesian_shape

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

geo_point

geo_point

boolean

geo_point

geo_shape

boolean

geo_shape

geo_point

boolean

geo_shape

geo_shape

boolean

示例

FROM airport_city_boundaries
| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))"))
| KEEP abbrev, airport, region, city, city_location
abbrev:keyword airport:text region:text city:keyword city_location:geo_point

SYX

Sanya Phoenix Int’l

天涯区

Sanya

POINT(109.5036 18.2533)

ST_WITHINedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_WITHIN(geomA,geomB)

参数

geomA
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。
geomB
类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，则函数返回 null。第二个参数必须与第一个参数具有相同的坐标系。这意味着无法组合 geo_* 和 cartesian_* 参数。

描述

返回第一个几何图形是否在第二个几何图形内。

这是 ST_CONTAINS 函数的逆运算。

支持的类型

geomA geomB result

cartesian_point

cartesian_point

boolean

cartesian_point

cartesian_shape

boolean

cartesian_shape

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

geo_point

geo_point

boolean

geo_point

geo_shape

boolean

geo_shape

geo_point

boolean

geo_shape

geo_shape

boolean

示例

FROM airport_city_boundaries
| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))"))
| KEEP abbrev, airport, region, city, city_location
abbrev:keyword airport:text region:text city:keyword city_location:geo_point

SYX

Sanya Phoenix Int’l

天涯区

Sanya

POINT(109.5036 18.2533)

ST_Xedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_X(point)

参数

point
类型为 geo_point 或 cartesian_point 的表达式。如果为 null，则函数返回 null。

描述

从提供的点中提取 x 坐标。如果点类型为 geo_point，则等效于提取 longitude 值。

支持的类型

point result

cartesian_point

double

geo_point

double

示例

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)
point:geo_point x:double y:double

POINT(42.97109629958868 14.7552534006536)

42.97109629958868

14.7552534006536

ST_Yedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

语法

ST_Y(point)

参数

point
类型为 geo_point 或 cartesian_point 的表达式。如果为 null，则函数返回 null。

描述

从提供的点中提取 y 坐标。如果点类型为 geo_point，则等效于提取 latitude 值。

支持的类型

point result

cartesian_point

double

geo_point

double

示例

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)
point:geo_point x:double y:double

POINT(42.97109629958868 14.7552534006536)

42.97109629958868

14.7552534006536

ES|QL 字符串函数edit

ES|QL 支持以下字符串函数

CONCATedit

语法

CONCAT(string1, string2[, ..., stringN])

参数

stringX
要连接的字符串。

描述

连接两个或多个字符串。

示例

FROM employees
| KEEP first_name, last_name
| EVAL fullname = CONCAT(first_name, " ", last_name)
first_name:keyword last_name:keyword fullname:keyword

Alejandro

McAlpine

Alejandro McAlpine

Amabile

Gomatam

Amabile Gomatam

Anneke

Preusig

Anneke Preusig

ENDS_WITHedit

语法

ENDS_WITH(str,suffix)

参数

str
字符串表达式。如果为 null，则函数返回 null。
suffix
字符串表达式。如果为 null，则函数返回 null。

描述

返回一个布尔值，指示关键字字符串是否以另一个字符串结尾。

支持的类型

str suffix result

keyword

keyword

boolean

text

text

boolean

示例

FROM employees
| KEEP last_name
| EVAL ln_E = ENDS_WITH(last_name, "d")
last_name:keyword ln_E:boolean

Awdeh

false

Azuma

false

Baek

false

Bamford

true

Bernatsky

false

FROM_BASE64edit

语法

FROM_BASE64(string)

参数

string
Base64 字符串。

描述

解码 Base64 字符串。

支持的类型

string result

keyword

keyword

text

keyword

示例

row a = "ZWxhc3RpYw=="
| eval d = from_base64(a)
a:keyword d:keyword

ZWxhc3RpYw==

elastic

LEFTedit

语法

LEFT(string,length)

参数

string
要从中返回子字符串的字符串。
length
要返回的字符数。

描述

返回从左侧开始从 string 中提取 length 个字符的子字符串。

支持的类型

string length result

keyword

integer

keyword

text

integer

keyword

示例

FROM employees
| KEEP last_name
| EVAL left = LEFT(last_name, 3)
| SORT last_name ASC
| LIMIT 5
last_name:keyword left:keyword

Awdeh

Awd

Azuma

Azu

Baek

Bae

Bamford

Bam

Bernatsky

Ber

LENGTHedit

语法

LENGTH(str)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

返回字符串的字符长度。

示例

FROM employees
| KEEP first_name, last_name
| EVAL fn_length = LENGTH(first_name)
first_name:keyword last_name:keyword fn_length:integer

Alejandro

McAlpine

9

Amabile

Gomatam

7

Anneke

Preusig

6

LOCATEedit

语法

LOCATE(string,substring,start)

参数

string
输入字符串
substring
要在输入字符串中查找的子字符串
start
起始索引

描述

返回一个整数，指示关键字子字符串在另一个字符串中的位置

支持的类型

string substring start result

keyword

keyword

integer

integer

keyword

keyword

integer

keyword

text

integer

integer

keyword

text

integer

text

keyword

integer

integer

text

keyword

integer

text

text

integer

integer

text

text

integer

LTRIMedit

语法

LTRIM(string)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

从字符串中删除前导空格。

支持的类型

string result

keyword

keyword

text

text

示例

ROW message = "   some text  ",  color = " red "
| EVAL message = LTRIM(message)
| EVAL color = LTRIM(color)
| EVAL message = CONCAT("'", message, "'")
| EVAL color = CONCAT("'", color, "'")
message:keyword color:keyword

'some text '

'red '

REPLACEedit

语法

REPLACE(string,regex,newString)

参数

str
字符串表达式。
regex
正则表达式。
newStr
替换字符串。

描述

该函数在字符串 str 中用替换字符串 newStr 替换正则表达式 regex 的任何匹配项。

如果任何参数为 null，则结果为 null。

支持的类型

string regex newString result

keyword

keyword

keyword

keyword

keyword

keyword

text

keyword

keyword

text

keyword

keyword

keyword

text

text

keyword

text

keyword

keyword

keyword

text

keyword

text

keyword

text

text

keyword

keyword

text

text

text

keyword

示例

此示例将任何出现的“World”替换为“Universe”。

ROW str = "Hello World"
| EVAL str = REPLACE(str, "World", "Universe")
| KEEP str
str:keyword

Hello Universe

RIGHTedit

语法

RIGHT(string,length)

参数

str
要从中返回子字符串的字符串。
length
要返回的字符数。

描述

返回从右侧开始从 str 中提取 length 个字符的子字符串。

支持的类型

string length result

keyword

integer

keyword

text

integer

keyword

示例

FROM employees
| KEEP last_name
| EVAL right = RIGHT(last_name, 3)
| SORT last_name ASC
| LIMIT 5
last_name:keyword right:keyword

Awdeh

deh

Azuma

uma

Baek

aek

Bamford

ord

Bernatsky

sky

RTRIMedit

语法

RTRIM(string)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

从字符串中删除尾随空格。

支持的类型

string result

keyword

keyword

text

text

示例

ROW message = "   some text  ",  color = " red "
| EVAL message = RTRIM(message)
| EVAL color = RTRIM(color)
| EVAL message = CONCAT("'", message, "'")
| EVAL color = CONCAT("'", color, "'")
message:keyword color:keyword

' some text'

' red'

SPLITedit

SPLIT(string,delim)

参数

str
字符串表达式。如果为 null，则函数返回 null。
delim
分隔符。目前仅支持单字节分隔符。

描述

将单值字符串拆分为多个字符串。

支持的类型

string delim result

keyword

keyword

keyword

text

text

keyword

示例

ROW words="foo;bar;baz;qux;quux;corge"
| EVAL word = SPLIT(words, ";")
words:keyword word:keyword

foo;bar;baz;qux;quux;corge

[foo,bar,baz,qux,quux,corge]

STARTS_WITHedit

语法

STARTS_WITH(str,prefix)

参数

str
字符串表达式。如果为 null，则函数返回 null。
prefix
字符串表达式。如果为 null，则函数返回 null。

描述

返回一个布尔值，指示关键字字符串是否以另一个字符串开头。

支持的类型

str prefix result

keyword

keyword

boolean

text

text

boolean

示例

FROM employees
| KEEP last_name
| EVAL ln_S = STARTS_WITH(last_name, "B")
last_name:keyword ln_S:boolean

Awdeh

false

Azuma

false

Baek

true

Bamford

true

Bernatsky

true

SUBSTRINGedit

语法

SUBSTRING(string,start,length)

参数

str
字符串表达式。如果为 null，则函数返回 null。
start
起始位置。
length
从起始位置开始的子字符串的长度。可选；如果省略，则返回 start 之后的所有位置。

描述

返回字符串的子字符串，由起始位置和可选长度指定。

支持的类型

string start length result

keyword

integer

integer

keyword

text

integer

integer

keyword

示例

此示例返回每个姓氏的前三个字符

FROM employees
| KEEP last_name
| EVAL ln_sub = SUBSTRING(last_name, 1, 3)
last_name:keyword ln_sub:keyword

Awdeh

Awd

Azuma

Azu

Baek

Bae

Bamford

Bam

Bernatsky

Ber

负起始位置被解释为相对于字符串的结尾。此示例返回每个姓氏的最后三个字符

FROM employees
| KEEP last_name
| EVAL ln_sub = SUBSTRING(last_name, -3, 3)
last_name:keyword ln_sub:keyword

Awdeh

deh

Azuma

uma

Baek

aek

Bamford

ord

Bernatsky

sky

如果省略长度，则 substring 返回字符串的剩余部分。此示例返回除第一个字符之外的所有字符

FROM employees
| KEEP last_name
| EVAL ln_sub = SUBSTRING(last_name, 2)
last_name:keyword ln_sub:keyword

Awdeh

wdeh

Azuma

zuma

Baek

aek

Bamford

amford

Bernatsky

ernatsky

TO_BASE64edit

语法

TO_BASE64(string)

参数

string
字符串。

描述

将字符串编码为 Base64 字符串。

支持的类型

string result

keyword

keyword

text

keyword

示例

row a = "elastic"
| eval e = to_base64(a)
a:keyword e:keyword

elastic

ZWxhc3RpYw==

TO_LOWERedit

语法

TO_LOWER(str)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

返回一个新的字符串，表示输入字符串转换为小写。

支持的类型

str result

keyword

keyword

text

text

示例

ROW message = "Some Text"
| EVAL message_lower = TO_LOWER(message)
message:keyword message_lower:keyword

Some Text

some text

TO_UPPERedit

语法

TO_UPPER(str)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

返回一个新的字符串，表示输入字符串转换为大写。

支持的类型

str result

keyword

keyword

text

text

示例

ROW message = "Some Text"
| EVAL message_upper = TO_UPPER(message)
message:keyword message_upper:keyword

Some Text

SOME TEXT

TRIMedit

语法

TRIM(string)

参数

str
字符串表达式。如果为 null，则函数返回 null。

描述

删除字符串中前导和尾随空格。

支持的类型

string result

keyword

keyword

text

text

示例

ROW message = "   some text  ",  color = " red "
| EVAL message = TRIM(message)
| EVAL color = TRIM(color)
message:s color:s

some text

red

ES|QL 类型转换函数edit

ES|QL 支持从字符串字面量到某些数据类型的隐式转换。有关详细信息，请参阅 隐式转换。

ES|QL 支持以下类型转换函数

TO_BOOLEANedit

别名

TO_BOOL

语法

TO_BOOLEAN(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为布尔值。

字符串值为 "true" 将不区分大小写地转换为布尔值 true。对于其他任何值，包括空字符串，该函数将返回 false。

数值 0 将转换为 false，其他任何值将转换为 true。

支持的类型

输入类型必须为字符串或数字类型。

示例

ROW str = ["true", "TRuE", "false", "", "yes", "1"]
| EVAL bool = TO_BOOLEAN(str)
str:keyword bool:boolean

["true", "TRuE", "false", "", "yes", "1"]

[true, true, false, false, false, false]

TO_CARTESIANPOINTedit

语法

TO_CARTESIANPOINT(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为 point 值。

只有当字符串符合 WKT 点 格式时，才能成功转换。

支持的类型

字段 result

cartesian_point

cartesian_point

keyword

cartesian_point

text

cartesian_point

示例

ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"]
| MV_EXPAND wkt
| EVAL pt = TO_CARTESIANPOINT(wkt)
wkt:keyword pt:cartesian_point

"POINT(4297.11 -1475.53)"

POINT(4297.11 -1475.53)

"POINT(7580.93 2272.77)"

POINT(7580.93 2272.77)

TO_CARTESIANSHAPEedit

语法

TO_CARTESIANSHAPE(v)

参数

v
输入值。输入可以是单值或多值列或表达式。输入类型必须为字符串、cartesian_shape 或 cartesian_point。

描述

将输入值转换为 cartesian_shape 值。

只有当字符串符合 WKT 格式时，才能成功转换。

支持的类型

字段 result

cartesian_point

cartesian_shape

cartesian_shape

cartesian_shape

keyword

cartesian_shape

text

cartesian_shape

示例

ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))"]
| MV_EXPAND wkt
| EVAL geom = TO_CARTESIANSHAPE(wkt)
wkt:keyword geom:cartesian_shape

"POINT(4297.11 -1475.53)"

POINT(4297.11 -1475.53)

"POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97"

POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97

TO_DATETIMEedit

别名

TO_DT

语法

TO_DATETIME(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为日期值。

只有当字符串符合格式 yyyy-MM-dd'T'HH:mm:ss.SSS'Z' 时，才能成功转换。要转换其他格式的日期，请使用 DATE_PARSE。

支持的类型

输入类型必须为字符串或数字类型。

示例

ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]
| EVAL datetime = TO_DATETIME(string)
string:keyword datetime:date

["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]

[1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z]

请注意，在此示例中，源多值字段中的最后一个值未转换。原因是，如果日期格式不符合要求，则转换将导致 null 值。发生这种情况时，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"

如果输入参数为数字类型，则其值将被解释为自 Unix 纪元 后的毫秒数。例如

ROW int = [0, 1]
| EVAL dt = TO_DATETIME(int)
int:integer dt:date

[0, 1]

[1970-01-01T00:00:00.000Z, 1970-01-01T00:00:00.001Z]

TO_DEGREESedit

语法

TO_DEGREES(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将以 弧度 为单位的数字转换为以 度 为单位的数字。

支持的类型

输入类型必须为数字类型，结果始终为 double。

示例

ROW rad = [1.57, 3.14, 4.71]
| EVAL deg = TO_DEGREES(rad)
rad:double deg:double

[1.57, 3.14, 4.71]

[89.95437383553924, 179.9087476710785, 269.86312150661774]

TO_DOUBLEedit

别名

TO_DBL

语法

TO_DOUBLE(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为双精度值。

如果输入参数为日期类型，则其值将被解释为自 Unix 纪元 后的毫秒数，转换为双精度值。

布尔值 true 将转换为双精度值 1.0，false 将转换为 0.0。

支持的类型

输入类型必须为布尔值、日期、字符串或数字类型。

示例

ROW str1 = "5.20128E11", str2 = "foo"
| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2)
str1:keyword str2:keyword dbl:double dbl1:double dbl2:double

5.20128E11

foo

5.20128E11

5.20128E11

null

请注意，在此示例中，字符串的最后一次转换是不可能的。发生这种情况时，结果为 null 值。在这种情况下，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"java.lang.NumberFormatException: For input string: \"foo\""

TO_GEOPOINTedit

语法

TO_GEOPOINT(v)

参数

v
输入值。输入可以是单值或多值列或表达式。输入类型必须为字符串或 geo_point。

描述

将输入值转换为 geo_point 值。

支持的类型

字段 result

geo_point

geo_point

keyword

geo_point

text

geo_point

只有当字符串符合 WKT 点 格式时，才能成功转换。

示例

ROW wkt = "POINT(42.97109630194 14.7552534413725)"
| EVAL pt = TO_GEOPOINT(wkt)
wkt:keyword pt:geo_point

"POINT(42.97109630194 14.7552534413725)"

POINT(42.97109630194 14.7552534413725)

TO_GEOSHAPEedit

语法

TO_GEOPOINT(v)

参数

v
输入值。输入可以是单值或多值列或表达式。输入类型必须为字符串、geo_shape 或 geo_point。

描述

将输入值转换为 geo_shape 值。

只有当字符串符合 WKT 格式时，才能成功转换。

支持的类型

字段 result

geo_point

geo_shape

geo_shape

geo_shape

keyword

geo_shape

text

geo_shape

示例

ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
| EVAL geom = TO_GEOSHAPE(wkt)
wkt:keyword geom:geo_shape

"POLYGON 30 10, 40 40, 20 40, 10 20, 30 10"

POLYGON 30 10, 40 40, 20 40, 10 20, 30 10

TO_INTEGERedit

别名

TO_INT

语法

TO_INTEGER(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为整数值。

如果输入参数为日期类型，则其值将被解释为自 Unix 纪元 后的毫秒数，转换为整数。

布尔值 true 将转换为整数 1，false 将转换为 0。

支持的类型

输入类型必须为布尔值、日期、字符串或数字类型。

示例

ROW long = [5013792, 2147483647, 501379200000]
| EVAL int = TO_INTEGER(long)
long:long int:integer

[5013792, 2147483647, 501379200000]

[5013792, 2147483647]

请注意，在此示例中，多值字段的最后一个值无法转换为整数。发生这种情况时，结果为 null 值。在这种情况下，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"

TO_IPedit

语法

TO_IP(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入字符串转换为 IP 值。

示例

ROW str1 = "1.1.1.1", str2 = "foo"
| EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2)
| WHERE CIDR_MATCH(ip1, "1.0.0.0/8")
str1:keyword str2:keyword ip1:ip ip2:ip

1.1.1.1

foo

1.1.1.1

null

请注意，在此示例中，字符串的最后一次转换是不可能的。发生这种情况时，结果为 null 值。在这种情况下，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."

TO_LONGedit

语法

TO_LONG(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为长整数值。

如果输入参数为日期类型，则其值将被解释为自 Unix 纪元 后的毫秒数，转换为长整数值。

布尔值 true 将转换为长整数值 1，false 将转换为 0。

支持的类型

输入类型必须为布尔值、日期、字符串或数字类型。

示例

ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo"
| EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3)
str1:keyword str2:keyword str3:keyword long1:long long2:long long3:long

2147483648

2147483648.2

foo

2147483648

2147483648

null

请注意，在此示例中，字符串的最后一次转换是不可能的。发生这种情况时，结果为 null 值。在这种情况下，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"java.lang.NumberFormatException: For input string: \"foo\""

TO_RADIANSedit

语法

TO_RADIANS(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将以 度 为单位的数字转换为以 弧度 为单位的数字。

支持的类型

输入类型必须为数字类型，结果始终为 double。

示例

ROW deg = [90.0, 180.0, 270.0]
| EVAL rad = TO_RADIANS(deg)
deg:double rad:double

[90.0, 180.0, 270.0]

[1.5707963267948966, 3.141592653589793, 4.71238898038469]

TO_STRINGedit

别名

TO_STR

TO_STRING(field)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为字符串。

支持的类型

字段 result

boolean

keyword

cartesian_point

keyword

cartesian_shape

keyword

datetime

keyword

double

keyword

geo_point

keyword

geo_shape

keyword

integer

keyword

ip

keyword

keyword

keyword

long

keyword

text

keyword

unsigned_long

keyword

version

keyword

示例

ROW a=10
| EVAL j = TO_STRING(a)
a:integer j:keyword

10

"10"

它在多值字段上也能正常工作

ROW a=[10, 9, 8]
| EVAL j = TO_STRING(a)
a:integer j:keyword

[10, 9, 8]

["10", "9", "8"]

TO_UNSIGNED_LONGedit

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

别名

TO_ULONG, TO_UL

语法

TO_UNSIGNED_LONG(v)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入值转换为无符号长整数值。

支持的类型

输入类型必须为布尔值、日期、字符串或数字类型。

如果输入参数为日期类型，则其值将被解释为自 Unix 纪元 后的毫秒数，转换为无符号长整数值。

布尔值 true 将转换为无符号长整数值 1，false 将转换为 0。

示例

ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo"
| EVAL long1 = TO_UNSIGNED_LONG(str1), long2 = TO_ULONG(str2), long3 = TO_UL(str3)
str1:keyword str2:keyword str3:keyword long1:unsigned_long long2:unsigned_long long3:unsigned_long

2147483648

2147483648.2

foo

2147483648

2147483648

null

请注意，在此示例中，字符串的最后一次转换是不可能的。发生这种情况时，结果为 null 值。在这种情况下，将向响应添加一个 警告 标头。该标头将提供有关失败来源的信息

"Line 1:133: evaluation of [TO_UL(str3)] failed, treating result as null. Only first 20 failures recorded."

以下标头将包含失败原因和有问题的 value

"java.lang.NumberFormatException: 字符 f 既不是十进制数字，也不是小数点，也不是“e”表示法指数标记。"

TO_VERSIONedit

别名

TO_VER

语法

TO_VERSION(field)

参数

v
输入值。输入可以是单值或多值列或表达式。

描述

将输入字符串转换为版本值。

支持的类型

字段 result

keyword

version

text

version

version

version

示例

ROW v = TO_VERSION("1.2.3")
v:version

1.2.3

ES|QL 多值函数edit

ES|QL 支持以下多值函数

MV_AVGedit

语法

MV_AVG(expression)

参数

表达式
多值表达式。

描述

将多值表达式转换为包含所有值的平均值的单值列。

支持的类型

number result

double

double

integer

double

long

double

unsigned_long

double

示例

ROW a=[3, 5, 1, 6]
| EVAL avg_a = MV_AVG(a)
a:integer avg_a:double

[3, 5, 1, 6]

3.75

MV_CONCATedit

语法

MV_CONCAT(string,delim)

参数

v
多值表达式。
delim
分隔符。

描述

将多值字符串表达式转换为包含所有值（以分隔符分隔）的连接的单值列。

支持的类型

string delim result

keyword

keyword

keyword

keyword

text

keyword

text

keyword

keyword

text

text

keyword

示例

ROW a=["foo", "zoo", "bar"]
| EVAL j = MV_CONCAT(a, ", ")
a:keyword j:keyword

["foo", "zoo", "bar"]

"foo, zoo, bar"

要连接非字符串列，请先调用 TO_STRING

ROW a=[10, 9, 8]
| EVAL j = MV_CONCAT(TO_STRING(a), ", ")
a:integer j:keyword

[10, 9, 8]

"10, 9, 8"

MV_COUNTedit

语法

MV_COUNT(field)

参数

v
多值表达式。

描述

将多值表达式转换为包含值数量的单值列。

支持的类型

字段 result

boolean

integer

cartesian_point

integer

cartesian_shape

integer

datetime

integer

double

integer

geo_point

integer

geo_shape

integer

integer

integer

ip

integer

keyword

integer

long

integer

text

integer

unsigned_long

integer

version

integer

示例

ROW a=["foo", "zoo", "bar"]
| EVAL count_a = MV_COUNT(a)
a:keyword count_a:integer

["foo", "zoo", "bar"]

3

MV_DEDUPEedit

语法

MV_DEDUPE(field)

参数

v
多值表达式。

描述

从多值表达式中删除重复项。

MV_DEDUPE 可能（但不一定）对列中的值进行排序。

支持的类型

字段 result

boolean

boolean

datetime

datetime

double

double

integer

integer

ip

ip

keyword

keyword

long

long

text

text

version

version

示例

ROW a=["foo", "foo", "bar", "foo"]
| EVAL dedupe_a = MV_DEDUPE(a)
a:keyword dedupe_a:keyword

["foo", "foo", "bar", "foo"]

["foo", "bar"]

MV_FIRSTedit

语法

MV_FIRST(field)

参数

v
多值表达式。

描述

将多值表达式转换为包含第一个值的单值列。这在从发出多值列的已知顺序函数（如 SPLIT）读取时最为有用。

从底层存储读取 多值字段 的顺序没有保证。它 通常 是升序的，但不要依赖于此。如果您需要最小值，请使用 MV_MIN 而不是 MV_FIRST。 MV_MIN 对排序的值进行了优化，因此 MV_FIRST 没有性能优势。

支持的类型

字段 result

boolean

boolean

cartesian_point

cartesian_point

cartesian_shape

cartesian_shape

datetime

datetime

double

double

geo_point

geo_point

geo_shape

geo_shape

integer

integer

ip

ip

keyword

keyword

long

long

text

text

unsigned_long

unsigned_long

version

version

示例

ROW a="foo;bar;baz"
| EVAL first_a = MV_FIRST(SPLIT(a, ";"))
a:keyword first_a:keyword

foo;bar;baz

"foo"

MV_LASTedit

语法

MV_LAST(field)

参数

v
多值表达式。

描述

将多值表达式转换为包含最后一个值的单值列。这在从发出多值列的已知顺序函数（如 SPLIT）读取时最为有用。

从底层存储读取 多值字段 的顺序没有保证。它 通常 是升序的，但不要依赖于此。如果您需要最大值，请使用 MV_MAX 而不是 MV_LAST。 MV_MAX 对排序的值进行了优化，因此 MV_LAST 没有性能优势。

支持的类型

字段 result

boolean

boolean

cartesian_point

cartesian_point

cartesian_shape

cartesian_shape

datetime

datetime

double

double

geo_point

geo_point

geo_shape

geo_shape

integer

integer

ip

ip

keyword

keyword

long

long

text

text

unsigned_long

unsigned_long

version

version

示例

ROW a="foo;bar;baz"
| EVAL last_a = MV_LAST(SPLIT(a, ";"))
a:keyword last_a:keyword

foo;bar;baz

"baz"

MV_MAXedit

语法

MV_MAX(field)

参数

v
多值表达式。

描述

将多值表达式转换为包含最大值的单值列。

支持的类型

字段 result

boolean

boolean

datetime

datetime

double

double

integer

integer

ip

ip

keyword

keyword

long

long

text

text

unsigned_long

unsigned_long

version

version

示例

ROW a=[3, 5, 1]
| EVAL max_a = MV_MAX(a)
a:integer max_a:integer

[3, 5, 1]

5

它可以用于任何列类型，包括 keyword 列。在这种情况下，它会选择最后一个字符串，逐字节比较它们的 utf-8 表示形式。

ROW a=["foo", "zoo", "bar"]
| EVAL max_a = MV_MAX(a)
a:keyword max_a:keyword

["foo", "zoo", "bar"]

"zoo"

MV_MEDIANedit

MV_MEDIAN(v)

参数

v
多值表达式。

描述

将多值列转换为包含中位数的单值列。

支持的类型

number result

double

double

integer

integer

long

long

unsigned_long

unsigned_long

示例

ROW a=[3, 5, 1]
| EVAL median_a = MV_MEDIAN(a)
a:integer median_a:integer

[3, 5, 1]

3

如果行对列具有偶数个值，则结果将是中间两个条目的平均值。如果列不是浮点数，则平均值将 向下 取整。

ROW a=[3, 7, 1, 6]
| EVAL median_a = MV_MEDIAN(a)
a:integer median_a:integer

[3, 7, 1, 6]

4

MV_MINedit

语法

MV_MIN(field)

参数

v
多值表达式。

描述

将多值表达式转换为包含最小值的单值列。

支持的类型

字段 result

boolean

boolean

datetime

datetime

double

double

integer

integer

ip

ip

keyword

keyword

long

long

text

text

unsigned_long

unsigned_long

version

version

示例

ROW a=[2, 1]
| EVAL min_a = MV_MIN(a)
a:integer min_a:integer

[2, 1]

1

它可以用于任何列类型，包括 keyword 列。在这种情况下，它会选择第一个字符串，逐字节比较它们的 utf-8 表示形式。

ROW a=["foo", "bar"]
| EVAL min_a = MV_MIN(a)
a:keyword min_a:keyword

["foo", "bar"]

"bar"

MV_SORTedit

语法

MV_SORT(field,order)

参数

字段
多值表达式。如果为 null，则函数返回 null。
order
排序顺序。有效选项为 ASC 和 DESC，默认值为 ASC。

描述

按字典顺序对多值表达式进行排序。

支持的类型

字段 order result

boolean

keyword

boolean

datetime

keyword

datetime

double

keyword

double

integer

keyword

integer

ip

keyword

ip

keyword

keyword

keyword

long

keyword

long

text

keyword

text

version

keyword

version

示例

ROW a = [4, 2, -3, 2]
| EVAL sa = mv_sort(a), sd = mv_sort(a, "DESC")
a:integer sa:integer sd:integer

[4, 2, -3, 2]

[-3, 2, 2, 4]

[4, 2, 2, -3]

MV_SLICEedit

语法

MV_SLICE(field,start,end)

参数

字段
多值表达式。如果为 null，则函数返回 null。
start
起始位置。如果为 null，则函数返回 null。start 参数可以为负数。索引 -1 用于指定列表中的最后一个值。
end
结束位置。可选；如果省略，则返回 start 处的索引。end 参数可以为负数。索引 -1 用于指定列表中的最后一个值。

描述

使用起始索引值和结束索引值返回多值字段的子集。

支持的类型

字段 start end result

boolean

integer

integer

boolean

cartesian_point

integer

integer

cartesian_point

cartesian_shape

integer

integer

cartesian_shape

datetime

integer

integer

datetime

double

integer

integer

double

geo_point

integer

integer

geo_point

geo_shape

integer

integer

geo_shape

integer

integer

integer

integer

ip

integer

integer

ip

keyword

integer

integer

keyword

long

integer

integer

long

text

integer

integer

text

version

integer

integer

version

示例

row a = [1, 2, 2, 3]
| eval a1 = mv_slice(a, 1), a2 = mv_slice(a, 2, 3)
a:integer a1:integer a2:integer

[1, 2, 2, 3]

2

[2, 3]

 
row a = [1, 2, 2, 3]
| eval a1 = mv_slice(a, -2), a2 = mv_slice(a, -3, -1)
a:integer a1:integer a2:integer

[1, 2, 2, 3]

2

[2, 2, 3]

MV_SUMedit

MV_SUM(v)

参数

v
多值表达式。

描述

将多值列转换为包含所有值的总和的单值列。

支持的类型

number result

double

double

integer

integer

long

long

unsigned_long

unsigned_long

示例

ROW a=[3, 5, 6]
| EVAL sum_a = MV_SUM(a)
a:integer sum_a:integer

[3, 5, 6]

14

MV_ZIPedit

语法

MV_ZIP(string1,string2,delim)

参数

mvLeft
多值表达式。
mvRight
多值表达式。
delim
分隔符。可选；如果省略，则 , 用作默认分隔符。

描述

使用分隔符将两个多值字段中的值组合在一起。

支持的类型

string1 string2 delim result

keyword

keyword

keyword

keyword

text

text

text

keyword

示例

ROW a = ["x", "y", "z"], b = ["1", "2"]
| EVAL c = mv_zip(a, b, "-")
| KEEP a, b, c
a:keyword b:keyword c:keyword

[x, y, z]

[1 ,2]

[x-1, y-2, z]

ES|QL 运算符edit

用于与一个或多个表达式进行比较的布尔运算符。

二元运算符edit

相等edit

lhs==rhs

检查两个字段是否相等。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

boolean

boolean

boolean

cartesian_point

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

geo_point

geo_point

boolean

geo_shape

geo_shape

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

不相等 !=edit

lhs!=rhs

检查两个字段是否不相等。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

boolean

boolean

boolean

cartesian_point

cartesian_point

boolean

cartesian_shape

cartesian_shape

boolean

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

geo_point

geo_point

boolean

geo_shape

geo_shape

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

小于 <edit

lhs<rhs

检查一个字段是否小于另一个字段。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

小于或等于 <=edit

lhs<=rhs

检查一个字段是否小于或等于另一个字段。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

大于 >edit

lhs>rhs

检查一个字段是否大于另一个字段。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

大于或等于 >=edit

lhs>=rhs

检查一个字段是否大于或等于另一个字段。如果任一字段为 多值，则结果为 null。

如果比较的一侧是常量，而另一侧是索引中的字段（该字段同时具有 index 和 doc_values），则将其推送到底层搜索索引。

支持的类型

支持的类型

lhs rhs result

datetime

datetime

boolean

double

double

boolean

double

integer

boolean

double

long

boolean

integer

double

boolean

integer

integer

boolean

integer

long

boolean

ip

ip

boolean

keyword

keyword

boolean

keyword

text

boolean

long

double

boolean

long

integer

boolean

long

long

boolean

text

keyword

boolean

text

text

boolean

unsigned_long

unsigned_long

boolean

version

version

boolean

加 +edit

lhs+rhs

将两个数字加在一起。如果任一字段为 多值，则结果为 null。

支持的类型

支持的类型

lhs rhs result

date_period

date_period

date_period

date_period

datetime

datetime

datetime

date_period

datetime

datetime

time_duration

datetime

double

double

double

double

integer

double

double

long

double

integer

double

double

integer

integer

integer

integer

long

long

long

double

double

long

integer

long

long

long

long

time_duration

datetime

datetime

time_duration

time_duration

time_duration

unsigned_long

unsigned_long

unsigned_long

减 -edit

lhs-rhs

从一个数字中减去另一个数字。如果任一字段为 多值，则结果为 null。

支持的类型

支持的类型

lhs rhs result

date_period

date_period

date_period

datetime

date_period

datetime

datetime

time_duration

datetime

double

double

double

integer

integer

integer

long

long

long

time_duration

time_duration

time_duration

unsigned_long

unsigned_long

unsigned_long

乘 *edit

lhs*rhs

将两个数字相乘。如果任一字段为 多值，则结果为 null。

支持的类型

支持的类型

lhs rhs result

double

double

double

integer

integer

integer

long

long

long

unsigned_long

unsigned_long

unsigned_long

除 /edit

lhs/rhs

用一个数字除以另一个数字。如果任一字段为 多值，则结果为 null。

两个整数类型的除法将产生一个整数结果，向 0 取整。如果您需要浮点数除法，请将其中一个参数包装在 TO_DOUBLE 中。

支持的类型

支持的类型

lhs rhs result

double

double

double

double

integer

double

double

long

double

integer

double

double

integer

integer

integer

integer

long

long

long

double

double

long

integer

long

long

long

long

unsigned_long

unsigned_long

unsigned_long

模 %edit

lhs%rhs

用一个数字除以另一个数字并返回余数。如果任一字段为 多值，则结果为 null。

支持的类型

支持的类型

lhs rhs result

double

double

double

double

integer

double

double

long

double

integer

double

double

integer

integer

integer

integer

long

long

long

double

double

long

integer

long

long

long

long

unsigned_long

unsigned_long

unsigned_long

一元运算符edit

唯一的单目运算符是取反 (-)

-v

支持的类型

支持的类型

v result

date_period

date_period

double

double

integer

integer

long

long

time_duration

time_duration

逻辑运算符edit

支持以下逻辑运算符

  • AND
  • OR
  • NOT

IS NULL 和 IS NOT NULL 谓词edit

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

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

Basil

Tramer

Florian

Syrotiuk

Lucien

Rosenbaum

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

84

INedit

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

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

1

4

3

LIKEedit

使用 LIKE 通过使用通配符来根据字符串模式过滤数据。 LIKE 通常作用于放置在运算符左侧的字段，但它也可以作用于常量（文字）表达式。运算符的右侧表示模式。

支持以下通配符

  • * 匹配零个或多个字符。
  • ? 匹配一个字符。
FROM employees
| WHERE first_name LIKE "?b*"
| KEEP first_name, last_name
first_name:keyword last_name:keyword

Ebbe

Callaway

Eberhardt

Terkki

RLIKEedit

使用 RLIKE 通过使用 正则表达式 来根据字符串模式过滤数据。 RLIKE 通常作用于放置在运算符左侧的字段，但它也可以作用于常量（文字）表达式。运算符的右侧表示模式。

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

Alejandro

McAlpine
« ES|QL 命令 ES|QL 元数据字段 »