ES|QL 函数和运算符

函数概述

编辑

聚合函数

AVG
COUNT
COUNT_DISTINCT
MAX
MEDIAN
MEDIAN_ABSOLUTE_DEVIATION
MIN
PERCENTILE
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 ST_CENTROID_AGG
SUM
TOP
VALUES
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 WEIGHTED_AVG

分组函数

BUCKET

条件函数和表达式

日期和时间函数

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

字符串函数

类型转换函数

TO_BOOLEAN
TO_CARTESIANPOINT
TO_CARTESIANSHAPE
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_DATEPERIOD
TO_DATETIME
TO_DEGREES
TO_DOUBLE
TO_GEOPOINT
TO_GEOSHAPE
TO_INTEGER
TO_IP
TO_LONG
TO_RADIANS
TO_STRING
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_TIMEDURATION
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_UNSIGNED_LONG
TO_VERSION

多值函数

运算符概述

编辑

运算符

ES|QL 聚合函数

编辑

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

AVG
COUNT
COUNT_DISTINCT
MAX
MEDIAN
MEDIAN_ABSOLUTE_DEVIATION
MIN
PERCENTILE
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 ST_CENTROID_AGG
SUM
TOP
VALUES
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 WEIGHTED_AVG

`AVG`

编辑

语法

参数

number

描述

数值字段的平均值。

支持的类型

number	结果
double	double
integer	double
long	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`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
boolean	long
cartesian_point	long
date	long
double	long
geo_point	long
integer	long
ip	long
keyword	long
long	long
text	long
unsigned_long	long
version	long

示例

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

要计算表达式返回 TRUE 的次数，请使用 WHERE 命令删除不应包含的行。

ROW n=1
| WHERE n < 0
| STATS COUNT(n)

COUNT(n):long
0

要基于两个不同的表达式计算相同数据流的计数，请使用模式 COUNT(<expression> OR NULL)。这基于语言的三值逻辑（3VL）：TRUE OR NULL 为 TRUE，但 FALSE OR NULL 为 NULL，加上 COUNT 处理 NULL`s: `COUNT(TRUE) 和 COUNT(FALSE) 均为 1，但 COUNT(NULL) 为 0。

ROW n=1
| STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL)

COUNT(n > 0 OR NULL):long	COUNT(n < 0 OR NULL):long
1	0

`COUNT_DISTINCT`

编辑

语法

参数

field: 要计算其不同值的列或文字。
precision: 精度阈值。请参阅计数近似。最大支持值为 40000。高于此数字的阈值将与阈值 40000 具有相同的效果。默认值为 3000。

描述

返回不同值的近似数量。

支持的类型

field	precision	结果
boolean	integer	long
boolean	long	long
boolean	unsigned_long	long
boolean		long
date	integer	long
date	long	long
date	unsigned_long	long
date		long
double	integer	long
double	long	long
double	unsigned_long	long
double		long
integer	integer	long
integer	long	long
integer	unsigned_long	long
integer		long
ip	integer	long
ip	long	long
ip	unsigned_long	long
ip		long
keyword	integer	long
keyword	long	long
keyword	unsigned_long	long
keyword		long
long	integer	long
long	long	long
long	unsigned_long	long
long		long
text	integer	long
text	long	long
text	unsigned_long	long
text		long
version	integer	long
version	long	long
version	unsigned_long	long
version		long

示例

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`

编辑

语法

参数

field

描述

字段的最大值。

支持的类型

field	结果
boolean	boolean
date	date
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	text
version	version

示例

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`

编辑

语法

参数

number

描述

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

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

支持的类型

number	结果
double	double
integer	double
long	double

示例

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 也是非确定性的。这意味着使用相同的数据可能会得到略微不同的结果。

`MEDIAN_ABSOLUTE_DEVIATION`

编辑

语法

参数

number

描述

返回中位数绝对偏差，一种变异性度量。它是一个稳健的统计量，这意味着它对于描述可能存在异常值或可能不服从正态分布的数据很有用。对于此类数据，它可能比标准偏差更具描述性。它的计算方法是每个数据点与其整个样本中位数偏差的中位数。也就是说，对于随机变量 X，中位数绝对偏差为 median(|median(X) - X|)。

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

支持的类型

number	结果
double	double
integer	double
long	double

示例

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

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

`MIN`

编辑

语法

参数

field

描述

字段的最小值。

支持的类型

field	结果
boolean	boolean
date	date
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	text
version	version

示例

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`

编辑

语法

参数

number
百分位数

描述

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

支持的类型

number	百分位数	结果
double	double	double
double	integer	double
double	long	double
integer	double	double
integer	integer	double
integer	long	double
long	double	double
long	integer	double
long	long	double

示例

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`

编辑

语法

参数

field

描述

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

支持的类型

field	结果
cartesian_point	cartesian_point
geo_point	geo_point

示例

FROM airports
| STATS centroid=ST_CENTROID_AGG(location)

centroid:geo_point
POINT(-0.030548143003023033 24.37553649504829)

`SUM`

编辑

语法

参数

number

描述

数字表达式的总和。

支持的类型

number	结果
double	double
integer	long
long	long

示例

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

`TOP`

编辑

语法

参数

field: 要为其收集最高值的字段。
限制: 要收集的最大值数。
顺序: 计算最高值的顺序。可以是 asc 或 desc。

描述

收集字段的最高值。包括重复的值。

支持的类型

field	限制	顺序	结果
boolean	integer	keyword	boolean
date	integer	keyword	date
double	integer	keyword	double
integer	integer	keyword	integer
ip	integer	keyword	ip
keyword	integer	keyword	keyword
long	integer	keyword	long
text	integer	keyword	text

示例

FROM employees
| STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary)

top_salaries:integer	top_salary:integer
[74999, 74970, 74572]	74999

`VALUES`

编辑

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

语法

参数

field

描述

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

支持的类型

field	结果
boolean	boolean
date	date
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	text
version	version

示例

  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 尚未将聚合扩展到内存之外。因此，此聚合将一直有效，直到它用于收集超过内存容量的值为止。一旦收集了太多值，它将导致查询失败并出现断路器错误。

`WEIGHTED_AVG`

编辑

语法

参数

number: 数值。
权重: 数值权重。

描述

数字表达式的加权平均值。

支持的类型

number	权重	结果
double	double	double
double	integer	double
double	long	double
integer	double	double
integer	integer	double
integer	long	double
long	double	double
long	integer	double
long	long	double

示例

FROM employees
| STATS w_avg = WEIGHTED_AVG(salary, height) by languages
| EVAL w_avg = ROUND(w_avg)
| KEEP w_avg, languages
| SORT languages

w_avg:double	languages:integer
51464.0	1
48477.0	2
52379.0	3
47990.0	4
42119.0	5
52142.0	null

ES|QL 分组函数

编辑

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

BUCKET

`BUCKET`

编辑

语法

参数

field: 用于派生桶的数字或日期表达式。
桶: 目标桶数，或如果省略了from和to参数，则为所需的桶大小。
from: 范围的开始。可以是数字、日期或以字符串表示的日期。
to: 范围的结束。可以是数字、日期或以字符串表示的日期。

描述

根据日期时间或数字输入创建值组 - 桶。桶的大小可以由直接提供，也可以根据推荐的计数和值范围来选择。

支持的类型

field	桶	from	to	结果
date	date_period			date
date	integer	date	date	date
date	integer	date	keyword	date
date	integer	date	text	date
date	integer	keyword	date	date
date	integer	keyword	keyword	date
date	integer	keyword	text	date
date	integer	text	date	date
date	integer	text	keyword	date
date	integer	text	text	date
date	time_duration			date
double	double			double
double	integer	double	double	double
double	integer	double	integer	double
double	integer	double	long	double
double	integer	integer	double	double
double	integer	integer	integer	double
double	integer	integer	long	double
double	integer	long	double	double
double	integer	long	integer	double
double	integer	long	long	double
double	integer			double
double	long			double
integer	double			double
integer	integer	double	double	double
integer	integer	double	integer	double
integer	integer	double	long	double
integer	integer	integer	double	double
integer	integer	integer	integer	double
integer	integer	integer	long	double
integer	integer	long	double	double
integer	integer	long	integer	double
integer	integer	long	long	double
integer	integer			double
integer	long			double
long	double			double
long	integer	double	double	double
long	integer	double	integer	double
long	integer	double	long	double
long	integer	integer	double	double
long	integer	integer	integer	double
long	integer	integer	long	double
long	integer	long	double	double
long	integer	long	integer	double
long	integer	long	long	double
long	integer			double
long	long			double

示例

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())

COUNT(*):long	bucket:date

创建 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 条件函数和表达式

编辑

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

`CASE`

编辑

语法

参数

condition: 条件。
trueValue: 当相应的条件是第一个计算结果为true时返回的值。当没有条件匹配时，返回默认值。
elseValue: 当没有条件计算结果为true时返回的值。

描述

接受条件和值的配对。该函数返回属于第一个计算结果为true的条件的值。如果参数个数为奇数，则最后一个参数为默认值，当没有条件匹配时返回该值。如果参数个数为偶数，并且没有条件匹配，则该函数返回null。

支持的类型

condition	trueValue	elseValue	结果
boolean	boolean	boolean	boolean
boolean	boolean		boolean
boolean	cartesian_point	cartesian_point	cartesian_point
boolean	cartesian_point		cartesian_point
boolean	cartesian_shape	cartesian_shape	cartesian_shape
boolean	cartesian_shape		cartesian_shape
boolean	date	date	date
boolean	date		date
boolean	double	double	double
boolean	double		double
boolean	geo_point	geo_point	geo_point
boolean	geo_point		geo_point
boolean	geo_shape	geo_shape	geo_shape
boolean	geo_shape		geo_shape
boolean	integer	integer	integer
boolean	integer		integer
boolean	ip	ip	ip
boolean	ip		ip
boolean	keyword	keyword	keyword
boolean	keyword		keyword
boolean	long	long	long
boolean	long		long
boolean	text	text	text
boolean	text		text
boolean	unsigned_long	unsigned_long	unsigned_long
boolean	unsigned_long		unsigned_long
boolean	version	version	version
boolean	version		version

示例

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

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

`COALESCE`

编辑

语法

参数

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

描述

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

支持的类型

first	rest	结果
boolean	boolean	boolean
boolean		boolean
cartesian_point	cartesian_point	cartesian_point
cartesian_shape	cartesian_shape	cartesian_shape
date	date	date
geo_point	geo_point	geo_point
geo_shape	geo_shape	geo_shape
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=null, b="b"
| EVAL COALESCE(a, b)

a:null	b:keyword	COALESCE(a, b):keyword
null	b	b

`GREATEST`

编辑

语法

参数

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

描述

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

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

支持的类型

first	rest	结果
boolean	boolean	boolean
boolean		boolean
date	date	date
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

`LEAST`

编辑

语法

参数

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

描述

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

支持的类型

first	rest	结果
boolean	boolean	boolean
boolean		boolean
date	date	date
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 日期时间函数

编辑

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

`DATE_DIFF`

编辑

语法

参数

unit: 时间差单位
startTimestamp: 表示开始时间戳的字符串
endTimestamp: 表示结束时间戳的字符串

描述

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

日期时间差单位
unit	缩写
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 使用的日期时间命名法相同。

支持的类型

unit	startTimestamp	endTimestamp	结果
keyword	date	date	integer
text	date	date	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

在以日历单位（如年、月等）进行减法时，仅计算完全经过的单位。要避免这种情况并获得余数，只需切换到下一个较小的单位并相应地进行日期计算即可。

ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"),
  start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"),
    end_24=TO_DATETIME("2024-12-31T23:59:59.999")
| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24)
| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24)
| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24)

end_23:date	start_24:date	end_24:date	end23_to_start24:integer	end23_to_end24:integer	start_to_end_24:integer
2023-12-31T23:59:59.999Z	2024-01-01T00:00:00.000Z	2024-12-31T23:59:59.999Z	0	1	0

`DATE_EXTRACT`

编辑

语法

参数

datePart: 要提取的日期部分。可以是：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。

描述

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

支持的类型

datePart	date	结果
keyword	date	long
text	date	long

示例

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_FORMAT`

编辑

语法

参数

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

描述

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

支持的类型

dateFormat	date	结果
keyword	date	keyword
text	date	keyword

示例

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_PARSE`

编辑

语法

参数

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

描述

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

支持的类型

datePattern	dateString	结果
keyword	keyword	date
keyword	text	date
text	keyword	date
text	text	date

示例

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_TRUNC`

编辑

语法

参数

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

描述

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

支持的类型

interval	date	结果
date_period	date	date
time_duration	date	date

示例

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

`NOW`

编辑

语法

参数

描述

返回当前日期和时间。

支持的类型

结果
date

示例

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 函数

编辑

ES|QL 支持以下 IP 函数

`CIDR_MATCH`

编辑

语法

参数

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

描述

如果提供的 IP 位于提供的 CIDR 块之一中，则返回 true。

支持的类型

ip	blockX	结果
ip	keyword	boolean
ip	text	boolean

示例

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

`IP_PREFIX`

编辑

语法

参数

ip: 类型为ip的 IP 地址（支持 IPv4 和 IPv6）。
prefixLengthV4: IPv4 地址的前缀长度。
prefixLengthV6: IPv6 地址的前缀长度。

描述

将 IP 截断到给定的前缀长度。

支持的类型

ip	prefixLengthV4	prefixLengthV6	结果
ip	integer	integer	ip

示例

row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);

ip4:ip	ip6:ip	ip4_prefix:ip	ip6_prefix:ip
1.2.3.4	fe80::cae2:65ff:fece:feb9	1.2.3.0	fe80::cae2:65ff:fece:0000

ES|QL 数学函数

编辑

ES|QL 支持以下数学函数

`ABS`

编辑

语法

参数

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

描述

返回绝对值。

支持的类型

number	结果
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

`ACOS`

编辑

语法

参数

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

描述

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

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

a:double	acos:double
.9	0.45102681179626236

`ASIN`

编辑

语法

参数

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

描述

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

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

a:double	asin:double
.9	1.1197695149986342

`ATAN`

编辑

语法

参数

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

描述

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

支持的类型

number	结果
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

`ATAN2`

编辑

语法

参数

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

描述

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

支持的类型

y_coordinate	x_coordinate	结果
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

`CBRT`

编辑

语法

参数

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

描述

返回一个数字的立方根。输入可以是任何数值，返回值始终为双精度浮点数。无穷大的立方根为 null。

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

ROW d = 1000.0
| EVAL c = cbrt(d)

d: double	c:double
1000.0	10.0

`CEIL`

编辑

语法

参数

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

描述

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

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

支持的类型

number	结果
double	double
integer	integer
long	long
unsigned_long	unsigned_long

示例

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

a:double
2

`COS`

编辑

语法

参数

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

描述

返回一个角度的余弦。

支持的类型

angle	结果
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

`COSH`

编辑

语法

参数

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

描述

返回一个数字的双曲余弦。

支持的类型

number	结果
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

`E`

编辑

语法

参数

描述

返回欧拉数。

支持的类型

结果
double

示例

ROW E()

E():double
2.718281828459045

`EXP`

编辑

语法

参数

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

描述

返回 e 的给定数字次幂的值。

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

ROW d = 5.0
| EVAL s = EXP(d)

d: double	s:double
5.0	148.413159102576603

`FLOOR`

编辑

语法

参数

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

描述

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

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

支持的类型

number	结果
double	double
integer	integer
long	long
unsigned_long	unsigned_long

示例

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

a:double
1

`HYPOT`

编辑

语法

参数

number1: 数值表达式。如果为null，则函数返回null。
number2: 数值表达式。如果为null，则函数返回null。

描述

返回两个数字的斜边。输入可以是任何数值，返回值始终为双精度浮点数。无穷大的斜边为 null。

支持的类型

number1	number2	结果
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 a = 3.0, b = 4.0
| EVAL c = HYPOT(a, b)

a:double	b:double	c:double
3.0	4.0	5.0

`LOG`

编辑

语法

参数

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

描述

返回一个值以某个底数的对数。输入可以是任何数值，返回值始终为双精度浮点数。零、负数和底数为 1 的对数将返回null以及警告。

支持的类型

base	number	结果
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

`LOG10`

编辑

语法

参数

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

描述

返回一个值以 10 为底的对数。输入可以是任何数值，返回值始终为双精度浮点数。0 和负数的对数将返回null以及警告。

支持的类型

number	结果
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

`PI`

编辑

语法

参数

描述

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

支持的类型

结果
double

示例

ROW PI()

PI():double
3.141592653589793

`POW`

编辑

语法

参数

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

描述

返回base的exponent次幂的值。

这里仍然可能导致双精度浮点数结果溢出；在这种情况下，将返回 null。

支持的类型

base	exponent	结果
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

`ROUND`

编辑

语法

参数

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

描述

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

支持的类型

number	decimals	结果
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

`SIGNUM`

编辑

语法

参数

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

描述

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

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

d: double	s:double
100	1.0

`SIN`

编辑

语法

参数

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

描述

返回一个角度的正弦。

支持的类型

angle	结果
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

`SINH`

编辑

语法

参数

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

描述

返回一个数字的双曲正弦。

支持的类型

number	结果
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

`SQRT`

编辑

语法

参数

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

描述

返回一个数字的平方根。输入可以是任何数值，返回值始终为双精度浮点数。负数和无穷大的平方根为 null。

支持的类型

number	结果
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

`TAN`

编辑

语法

参数

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

描述

返回一个角度的正切。

支持的类型

angle	结果
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

`TANH`

编辑

语法

参数

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

描述

返回一个数字的双曲正切。

支持的类型

number	结果
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

`TAU`

编辑

语法

参数

描述

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

支持的类型

结果
double

示例

ROW TAU()

TAU():double
6.283185307179586

ES|QL 空间函数

编辑

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

`ST_INTERSECTS`

编辑

语法

参数

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	结果
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_DISJOINT`

编辑

语法

参数

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	结果
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	机场：文本	地区：文本	city:keyword	city_location:geo_point
ACA	胡安·N·阿尔瓦雷斯将军国际机场	阿卡普尔科德华雷斯	阿卡普尔科德华雷斯	POINT (-99.8825 16.8636)

`ST_CONTAINS`

编辑

语法

参数

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	结果
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	机场：文本	地区：文本	city:keyword	city_location:geo_point
SYX	三亚凤凰国际机场	天涯区	三亚	POINT(109.5036 18.2533)

`ST_WITHIN`

编辑

语法

参数

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	结果
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	机场：文本	地区：文本	city:keyword	city_location:geo_point
SYX	三亚凤凰国际机场	天涯区	三亚	POINT(109.5036 18.2533)

`ST_X`

编辑

语法

参数

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

描述

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

支持的类型

点	结果
cartesian_point	double
geo_point	double

示例

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

点：geo_point	x:double	y:double
POINT(42.97109629958868 14.7552534006536)	42.97109629958868	14.7552534006536

`ST_Y`

编辑

语法

参数

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

描述

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

支持的类型

点	结果
cartesian_point	double
geo_point	double

示例

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

点：geo_point	x:double	y:double
POINT(42.97109629958868 14.7552534006536)	42.97109629958868	14.7552534006536

`ST_DISTANCE`

编辑

语法

参数

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

描述

计算两点之间的距离。对于笛卡尔几何，这是与原始坐标相同单位的毕达哥拉斯距离。对于地理几何，这是沿大圆的圆形距离（以米为单位）。

支持的类型

geomA	geomB	结果
cartesian_point	cartesian_point	double
geo_point	geo_point	double

示例

FROM airports
| WHERE abbrev == "CPH"
| EVAL distance = ST_DISTANCE(location, city_location)
| KEEP abbrev, name, location, city_location, distance

缩写：k	name:text	location:geo_point	city_location:geo_point	距离：d
CPH	哥本哈根	POINT(12.6493508684508 55.6285017221528)	POINT(12.5683 55.6761)	7339.573896618216

ES|QL 字符串函数

编辑

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

`CONCAT`

编辑

语法

参数

字符串1: 要连接的字符串。
字符串2: 要连接的字符串。

描述

连接两个或多个字符串。

支持的类型

字符串1	字符串2	结果
keyword	keyword	keyword
keyword	text	keyword
text	keyword	keyword
text	text	keyword

示例

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

first_name:keyword	last_name:keyword	全名：关键字
Alejandro	McAlpine	亚历杭德罗·麦克阿尔平
Amabile	Gomatam	阿玛比尔·戈马塔姆
Anneke	Preusig	安妮克·普罗伊西格

`ENDS_WITH`

编辑

语法

参数

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

描述

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

支持的类型

str	后缀	结果
keyword	keyword	boolean
keyword	text	boolean
text	keyword	boolean
text	text	boolean

示例

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

last_name:keyword	ln_E：布尔值
阿夫德	false
阿祖马	false
白	false
班福德	true
伯纳茨基	false

`FROM_BASE64`

编辑

语法

参数

字符串: 一个 Base64 字符串。

描述

解码 Base64 字符串。

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

a：关键字	d：关键字
ZWxhc3RpYw==	elastic

`LEFT`

编辑

语法

参数

字符串: 要从中返回子字符串的字符串。
长度: 要返回的字符数。

描述

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

支持的类型

字符串	长度	结果
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：关键字
阿夫德	Awd
阿祖马	Azu
白	Bae
班福德	Bam
伯纳茨基	Ber

`LENGTH`

编辑

语法

参数

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

描述

返回字符串的字符长度。

支持的类型

字符串	结果
keyword	integer
text	integer

示例

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

first_name:keyword	last_name:keyword	fn_length：整数
Alejandro	McAlpine	9
Amabile	Gomatam	7
Anneke	Preusig	6

`LOCATE`

编辑

语法

参数

字符串: 输入字符串
子字符串: 要在输入字符串中定位的子字符串
开始: 起始索引

描述

返回一个整数，指示关键字子字符串在另一个字符串中的位置。如果找不到子字符串，则返回 0。请注意，字符串位置从 1 开始。

支持的类型

字符串	子字符串	开始	结果
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

示例

row a = "hello"
| eval a_ll = locate(a, "ll")

a：关键字	a_ll：整数
hello	3

`LTRIM`

编辑

语法

参数

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

描述

删除字符串开头的空格。

支持的类型

字符串	结果
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	颜色：关键字
'some text '	'red '

`REPEAT`

编辑

语法

参数

字符串: 字符串表达式。
number: 重复次数。

描述

返回一个字符串，该字符串通过将 string 与自身连接指定 number 次构造而成。

支持的类型

字符串	number	结果
keyword	integer	keyword
text	integer	keyword

示例

ROW a = "Hello!"
| EVAL triple_a = REPEAT(a, 3)

a：关键字	triple_a：关键字
Hello！	Hello！Hello！Hello！

`REPLACE`

编辑

语法

参数

字符串: 字符串表达式。
正则表达式: 正则表达式。
新字符串: 替换字符串。

描述

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

支持的类型

字符串	正则表达式	新字符串	结果
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：关键字
Hello Universe

`REVERSE`

编辑

语法

参数

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

描述

返回一个新的字符串，表示输入字符串的反向顺序。

如果 Elasticsearch 使用的 JDK 版本低于 20，则此操作将无法正确反转字素簇。Elastic Cloud 中与 Elasticsearch 捆绑的 JDK 都使用较新的 JDK。但是，如果您已明确切换到较旧的 JDK，则会看到诸如“👍🏽😊”之类的内容反转为“🏽👍😊”，而不是正确的“😊👍🏽”。

支持的类型

str	结果
keyword	keyword
text	text

示例

ROW message = "Some Text" | EVAL message_reversed = REVERSE(message);

message:keyword	message_reversed：关键字
Some Text	txeT emoS

REVERSE 也适用于 Unicode！它在反转期间将 Unicode 字素簇保持在一起。

ROW bending_arts = "💧🪨🔥💨" | EVAL bending_arts_reversed = REVERSE(bending_arts);

bending_arts：关键字	bending_arts_reversed：关键字
💧🪨🔥💨	💨🔥🪨💧

`RIGHT`

编辑

语法

参数

字符串: 要从中返回子字符串的字符串。
长度: 要返回的字符数。

描述

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

支持的类型

字符串	长度	结果
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：关键字
阿夫德	deh
阿祖马	uma
白	aek
班福德	ord
伯纳茨基	sky

`RTRIM`

编辑

语法

参数

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

描述

删除字符串末尾的空格。

支持的类型

字符串	结果
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	颜色：关键字
' some text'	' red'

`SPACE`

编辑

语法

参数

number: 结果中的空格数。

描述

返回由 number 个空格组成的字符串。

支持的类型

number	结果
integer	keyword

示例

ROW message = CONCAT("Hello", SPACE(1), "World!");

message:keyword
Hello World！

`SPLIT`

编辑

语法

参数

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

描述

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

支持的类型

字符串	分隔符	结果
keyword	keyword	keyword
keyword	text	keyword
text	keyword	keyword
text	text	keyword

示例

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

words：关键字	word：关键字
foo;bar;baz;qux;quux;corge	[foo,bar,baz,qux,quux,corge]

`STARTS_WITH`

编辑

语法

参数

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

描述

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

支持的类型

str	前缀	结果
keyword	keyword	boolean
keyword	text	boolean
text	keyword	boolean
text	text	boolean

示例

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

last_name:keyword	ln_S：布尔值
阿夫德	false
阿祖马	false
白	true
班福德	true
伯纳茨基	true

`SUBSTRING`

编辑

语法

参数

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

描述

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

支持的类型

字符串	开始	长度	结果
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：关键字
阿夫德	Awd
阿祖马	Azu
白	Bae
班福德	Bam
伯纳茨基	Ber

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

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

last_name:keyword	ln_sub：关键字
阿夫德	deh
阿祖马	uma
白	aek
班福德	ord
伯纳茨基	sky

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

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

last_name:keyword	ln_sub：关键字
阿夫德	wdeh
阿祖马	zuma
白	aek
班福德	amford
伯纳茨基	ernatsky

`TO_BASE64`

编辑

语法

参数

字符串: 一个字符串。

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

a：关键字	e：关键字
elastic	ZWxhc3RpYw==

`TO_LOWER`

编辑

语法

参数

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

描述

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

支持的类型

str	结果
keyword	keyword
text	text

示例

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

message:keyword	message_lower：关键字
Some Text	some text

`TO_UPPER`

编辑

语法

参数

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

描述

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

支持的类型

str	结果
keyword	keyword
text	text

示例

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

message:keyword	message_upper：关键字
Some Text	SOME TEXT

`TRIM`

编辑

语法

参数

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

描述

删除字符串开头和结尾的空格。

支持的类型

字符串	结果
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 类型转换函数

编辑

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

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

TO_BOOLEAN
TO_CARTESIANPOINT
TO_CARTESIANSHAPE
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_DATEPERIOD
TO_DATETIME
TO_DEGREES
TO_DOUBLE
TO_GEOPOINT
TO_GEOSHAPE
TO_INTEGER
TO_IP
TO_LONG
TO_RADIANS
TO_STRING
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_TIMEDURATION
[预览] 此功能处于技术预览阶段，可能在将来的版本中更改或删除。Elastic 会努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 TO_UNSIGNED_LONG
TO_VERSION

`TO_BOOLEAN`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
boolean	boolean
double	boolean
integer	boolean
keyword	boolean
long	boolean
text	boolean
unsigned_long	boolean

示例

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

str：关键字	bool：布尔值
["true", "TRuE", "false", "", "yes", "1"]	[true, true, false, false, false, false]

`TO_CARTESIANPOINT`

编辑

语法

参数

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

描述

将输入值转换为 cartesian_point 值。只有当字符串符合 WKT 点格式时，才能成功转换。

支持的类型

field	结果
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：关键字	pt：cartesian_point
"POINT(4297.11 -1475.53)"	POINT(4297.11 -1475.53)
"POINT(7580.93 2272.77)"	POINT(7580.93 2272.77)

`TO_CARTESIANSHAPE`

编辑

语法

参数

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

描述

将输入值转换为 cartesian_shape 值。只有当字符串符合 WKT 格式时，才能成功转换。

支持的类型

field	结果
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：关键字	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_DATEPERIOD`

编辑

语法

参数

field: 输入值。输入是一个有效的常量日期周期表达式。

描述

将输入值转换为 date_period 值。

支持的类型

field	结果
date_period	date_period
keyword	date_period
text	date_period

示例

row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days");

x：datetime	y：datetime	z：datetime
2024-01-01	2024-01-04	2023-12-29

`TO_DATETIME`

编辑

语法

参数

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

描述

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

请注意，使用此函数将纳秒分辨率转换为毫秒分辨率时，纳秒日期将被截断，而不是四舍五入。

支持的类型

field	结果
date	date
double	date
integer	date
keyword	date
long	date
text	date
unsigned_long	date

示例

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:关键字	datetime:日期
["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值。发生这种情况时，响应中会添加一个警告标题。标题将提供有关故障源的信息

"第1行:112: [TO_DATETIME(string)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值

"java.lang.IllegalArgumentException: 无法使用格式 [yyyy-MM-dd'T'HH:mm:ss.SSS'Z'] 解析日期字段 [1964-06-02 00:00:00]"

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

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

int:整数	dt:日期
[0, 1]	[1970-01-01T00:00:00.000Z, 1970-01-01T00:00:00.001Z]

`TO_DEGREES`

编辑

语法

参数

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

描述

将弧度表示的数字转换为度。

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

rad:双精度浮点数	deg:双精度浮点数
[1.57, 3.14, 4.71]	[89.95437383553924, 179.9087476710785, 269.86312150661774]

`TO_DOUBLE`

编辑

语法

参数

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

描述

将输入值转换为双精度浮点数。如果输入参数为日期类型，则其值将被解释为自Unix纪元以来的毫秒数，并转换为双精度浮点数。布尔值true 将转换为双精度浮点数1.0，false 将转换为0.0。

支持的类型

field	结果
boolean	double
counter_double	double
counter_integer	double
counter_long	double
date	double
double	double
integer	double
keyword	double
long	double
text	double
unsigned_long	double

示例

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

str1:关键字	str2:关键字	dbl:双精度浮点数	dbl1:双精度浮点数	dbl2:双精度浮点数
5.20128E11	foo	5.20128E11	5.20128E11	null

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

"第1行:115: [TO_DOUBLE(str2)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值："java.lang.NumberFormatException: For input string: "foo""

`TO_GEOPOINT`

编辑

语法

参数

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

描述

将输入值转换为geo_point值。只有当字符串符合WKT点格式时，才能成功转换。

支持的类型

field	结果
geo_point	geo_point
keyword	geo_point
text	geo_point

示例

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

wkt：关键字	pt:geo_point
"POINT(42.97109630194 14.7552534413725)"	POINT(42.97109630194 14.7552534413725)

`TO_GEOSHAPE`

编辑

语法

参数

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

描述

将输入值转换为geo_shape值。只有当字符串符合WKT格式时，才能成功转换。

支持的类型

field	结果
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：关键字	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_INTEGER`

编辑

语法

参数

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

描述

将输入值转换为整数。如果输入参数为日期类型，则其值将被解释为自Unix纪元以来的毫秒数，并转换为整数。布尔值true 将转换为整数1，false 将转换为0。

支持的类型

field	结果
boolean	integer
counter_integer	integer
date	integer
double	integer
integer	integer
keyword	integer
long	integer
text	integer
unsigned_long	integer

示例

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

long:长整数	int:整数
[5013792, 2147483647, 501379200000]	[5013792, 2147483647]

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

"第1行:61: [TO_INTEGER(long)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值

"org.elasticsearch.xpack.esql.core.InvalidArgumentException: [501379200000] 超出 [integer] 范围"

`TO_IP`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
ip	ip
keyword	ip
text	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:关键字	str2:关键字	ip1:ip	ip2:ip
1.1.1.1	foo	1.1.1.1	null

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

"第1行:68: [TO_IP(str2)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值

"java.lang.IllegalArgumentException: 'foo' 不是 IP 字符串字面量。"

`TO_LONG`

编辑

语法

参数

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

描述

将输入值转换为长整数。如果输入参数为日期类型，则其值将被解释为自Unix纪元以来的毫秒数，并转换为长整数。布尔值true 将转换为长整数1，false 将转换为0。

支持的类型

field	结果
boolean	long
counter_integer	long
counter_long	long
date	long
double	long
integer	long
keyword	long
long	long
text	long
unsigned_long	long

示例

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

str1:关键字	str2:关键字	str3:关键字	long1:长整数	long2:长整数	long3:长整数
2147483648	2147483648.2	foo	2147483648	2147483648	null

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

"第1行:113: [TO_LONG(str3)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值

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

`TO_RADIANS`

编辑

语法

参数

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

描述

将度表示的数字转换为弧度。

支持的类型

number	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

deg:双精度浮点数	rad:双精度浮点数
[90.0, 180.0, 270.0]	[1.5707963267948966, 3.141592653589793, 4.71238898038469]

`TO_STRING`

编辑

语法

参数

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

描述

将输入值转换为字符串。

支持的类型

field	结果
boolean	keyword
cartesian_point	keyword
cartesian_shape	keyword
date	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:关键字
10	"10"

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

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

a:integer	j:关键字
[10, 9, 8]	["10", "9", "8"]

`TO_TIMEDURATION`

编辑

语法

参数

field: 输入值。输入是一个有效的常量时间持续时间表达式。

描述

将输入值转换为time_duration值。

支持的类型

field	结果
keyword	time_duration
text	time_duration
time_duration	time_duration

示例

row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours");

x：datetime	y：datetime	z：datetime
2024-01-01	2024-01-01T03:00:00.000Z	2023-12-31T21:00:00.000Z

`TO_UNSIGNED_LONG`

编辑

语法

参数

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

描述

将输入值转换为无符号长整数。如果输入参数为日期类型，则其值将被解释为自Unix纪元以来的毫秒数，并转换为无符号长整数。布尔值true 将转换为无符号长整数1，false 将转换为0。

支持的类型

field	结果
boolean	unsigned_long
date	unsigned_long
double	unsigned_long
integer	unsigned_long
keyword	unsigned_long
long	unsigned_long
text	unsigned_long
unsigned_long	unsigned_long

示例

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

str1:关键字	str2:关键字	str3:关键字	long1:无符号长整数	long2:无符号长整数	long3:无符号长整数
2147483648	2147483648.2	foo	2147483648	2147483648	null

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

"第1行:133: [TO_UL(str3)] 的评估失败，将结果视为 null。仅记录前 20 个失败。"

后续标题将包含故障原因和有问题的数值

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

`TO_VERSION`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
keyword	version
text	version
version	version

示例

ROW v = TO_VERSION("1.2.3")

v:版本
1.2.3

ES|QL 多值函数

编辑

ES|QL 支持以下多值函数

`MV_APPEND`

编辑

语法

参数

field1
field2

描述

连接两个多值字段的值。

支持的类型

field1	field2	结果
boolean	boolean	boolean
cartesian_point	cartesian_point	cartesian_point
cartesian_shape	cartesian_shape	cartesian_shape
date	date	date
double	double	double
geo_point	geo_point	geo_point
geo_shape	geo_shape	geo_shape
integer	integer	integer
ip	ip	ip
keyword	keyword	keyword
long	long	long
text	text	text
version	version	version

`MV_AVG`

编辑

语法

参数

number: 多值表达式。

描述

将多值字段转换为包含所有值平均值的单值字段。

支持的类型

number	结果
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:双精度浮点数
[3, 5, 1, 6]	3.75

`MV_CONCAT`

编辑

语法

参数

字符串: 多值表达式。
分隔符: 分隔符。

描述

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

支持的类型

字符串	分隔符	结果
keyword	keyword	keyword
keyword	text	keyword
text	keyword	keyword
text	text	keyword

示例

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

a：关键字	j:关键字
["foo", "zoo", "bar"]	"foo, zoo, bar"

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

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

a:integer	j:关键字
[10, 9, 8]	"10, 9, 8"

`MV_COUNT`

编辑

语法

参数

field: 多值表达式。

描述

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

支持的类型

field	结果
boolean	integer
cartesian_point	integer
cartesian_shape	integer
date	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：关键字	count_a:整数
["foo", "zoo", "bar"]	3

`MV_DEDUPE`

编辑

语法

参数

field: 多值表达式。

描述

从多值字段中删除重复值。

MV_DEDUPE可能会，但也并非总是会对列中的值进行排序。

支持的类型

field	结果
boolean	boolean
cartesian_point	cartesian_point
cartesian_shape	cartesian_shape
date	date
double	double
geo_point	geo_point
geo_shape	geo_shape
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：关键字	dedupe_a:关键字
["foo", "foo", "bar", "foo"]	["foo", "bar"]

`MV_FIRST`

编辑

语法

参数

field: 多值表达式。

描述

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

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

支持的类型

field	结果
boolean	boolean
cartesian_point	cartesian_point
cartesian_shape	cartesian_shape
date	date
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：关键字	first_a:关键字
foo;bar;baz	"foo"

`MV_LAST`

编辑

语法

参数

field: 多值表达式。

描述

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

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

支持的类型

field	结果
boolean	boolean
cartesian_point	cartesian_point
cartesian_shape	cartesian_shape
date	date
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：关键字	last_a:关键字
foo;bar;baz	"baz"

`MV_MAX`

编辑

语法

参数

field: 多值表达式。

描述

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

支持的类型

field	结果
boolean	boolean
date	date
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:整数
[3, 5, 1]	5

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

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

a：关键字	max_a:关键字
["foo", "zoo", "bar"]	"zoo"

`MV_MEDIAN`

编辑

语法

参数

number: 多值表达式。

描述

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

支持的类型

number	结果
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:整数
[3, 5, 1]	3

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

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

a:integer	median_a:整数
[3, 7, 1, 6]	4

`MV_MEDIAN_ABSOLUTE_DEVIATION`

编辑

语法

参数

number: 多值表达式。

描述

将多值字段转换为包含中位数绝对偏差的单值字段。它是通过计算每个数据点与其样本中位数偏差的中位数来计算的。也就是说，对于随机变量X，中位数绝对偏差为median(|median(X) - X|)。

如果字段具有偶数个值，则中位数将计算为中间两个值的平均值。如果值不是浮点数，则平均值将向 0 取整。

支持的类型

number	结果
double	double
integer	integer
long	long
unsigned_long	unsigned_long

示例

ROW values = [0, 2, 5, 6]
| EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values)

values:integer	median_absolute_deviation:integer	median:integer
[0, 2, 5, 6]	2	3

`MV_MIN`

编辑

语法

参数

field: 多值表达式。

描述

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

支持的类型

field	结果
boolean	boolean
date	date
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：关键字	min_a:keyword
["foo", "bar"]	"bar"

`MV_PSERIES_WEIGHTED_SUM`

编辑

语法

参数

number: 多值表达式。
p: 它是一个常数，表示 P 系列中的p参数。它会影响每个元素对加权和的贡献。

描述

通过将输入列表中的每个元素乘以 P 系列中对应的项并计算总和，将多值表达式转换为单值列。

支持的类型

number	p	结果
double	double	double

示例

ROW a = [70.0, 45.0, 21.0, 21.0, 21.0]
| EVAL sum = MV_PSERIES_WEIGHTED_SUM(a, 1.5)
| KEEP sum

sum:double
94.45465156212452

`MV_SLICE`

编辑

语法

参数

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

描述

使用起始和结束索引值返回多值字段的子集。当从发出已知顺序的多值列的函数（如SPLIT或MV_SORT）读取时，这非常有用。

从底层存储读取多值字段的顺序没有保证。它通常是升序的，但不要依赖它。

支持的类型

field	开始	end	结果
boolean	integer	integer	boolean
cartesian_point	integer	integer	cartesian_point
cartesian_shape	integer	integer	cartesian_shape
date	integer	integer	date
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_SORT`

编辑

语法

参数

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

描述

按字典顺序对多值字段进行排序。

支持的类型

field	顺序	结果
boolean	keyword	boolean
date	keyword	date
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_SUM`

编辑

语法

参数

number: 多值表达式。

描述

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

支持的类型

number	结果
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_ZIP`

编辑

语法

参数

字符串1: 多值表达式。
字符串2: 多值表达式。
分隔符: 分隔符。可选；如果省略，则,用作默认分隔符。

描述

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

支持的类型

字符串1	字符串2	分隔符	结果
keyword	keyword	keyword	keyword
keyword	keyword	text	keyword
keyword	keyword		keyword
keyword	text	keyword	keyword
keyword	text	text	keyword
keyword	text		keyword
text	keyword	keyword	keyword
text	keyword	text	keyword
text	keyword		keyword
text	text	keyword	keyword
text	text	text	keyword
text	text		keyword

示例

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

a：关键字	b:keyword	c:keyword
[x, y, z]	[1 ,2]	[x-1, y-2, z]

ES|QL 运算符

编辑

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

二元运算符

编辑

相等性

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
boolean	boolean	boolean
cartesian_point	cartesian_point	boolean
cartesian_shape	cartesian_shape	boolean
date	date	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

不等式 `!=`

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
boolean	boolean	boolean
cartesian_point	cartesian_point	boolean
cartesian_shape	cartesian_shape	boolean
date	date	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

小于 `<`

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
date	date	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

小于或等于 `<=`

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
date	date	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

大于 `>`

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
date	date	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

大于或等于 `>=`

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
date	date	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

加法 `+`

编辑

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

支持的类型

支持的类型

lhs	rhs	结果
date	date_period	date
date	time_duration	date
date_period	date	date
date_period	date_period	date_period
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	date	date
time_duration	time_duration	time_duration
unsigned_long	unsigned_long	unsigned_long

减法 `-`

编辑

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

支持的类型

支持的类型

lhs	rhs	结果
date	date_period	date
date	time_duration	date
date_period	date_period	date_period
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	time_duration	time_duration
unsigned_long	unsigned_long	unsigned_long

乘法 `*`

编辑

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

支持的类型

支持的类型

lhs	rhs	结果
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

除法 `/`

编辑

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

两个整数类型的除法将产生一个整数结果，向 0 取整。如果您需要浮点数除法，请将Cast (::)其中一个参数转换为DOUBLE。

支持的类型

支持的类型

lhs	rhs	结果
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

取模 `%`

编辑

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

支持的类型

支持的类型

lhs	rhs	结果
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

一元运算符

编辑

唯一的一元运算符是负号 (-)

支持的类型

支持的类型

field	结果
date_period	date_period
double	double
integer	integer
long	long
time_duration	time_duration

逻辑运算符

编辑

支持以下逻辑运算符

AND
OR
NOT

`IS NULL` 和 `IS NOT NULL` 谓词

编辑

对于 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