ES|QL 函数和运算符

函数概述

编辑

聚合函数

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

分组函数

BUCKET

条件函数和表达式

日期和时间函数

IP 函数

数学函数

搜索函数

[预览] 此功能为技术预览版，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 约束。 MATCH
[预览] 此功能为技术预览版，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 约束。 QSTR

空间函数

字符串函数

类型转换函数

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

多值函数

运算符概述

编辑

运算符

二元运算符
一元运算符
逻辑运算符
IS NULL 和 IS NOT NULL 谓词
类型转换 (::)
IN
LIKE
RLIKE
[预览] 此功能为技术预览版，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 约束。搜索运算符

ES|QL 聚合函数

编辑

STATS 命令支持以下聚合函数

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

`AVG`

编辑

语法

参数

数字

描述

数值字段的平均值。

支持的类型

数字	结果
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 的方式：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
date_nanos	integer	long
date_nanos	long	long
date_nanos	unsigned_long	long
date_nanos		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
date_nanos	date_nanos
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
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`

编辑

语法

参数

数字

描述

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

与 PERCENTILE 类似，MEDIAN 通常是近似值。

支持的类型

数字	结果
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`

编辑

语法

参数

数字

描述

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

与 PERCENTILE 类似，MEDIAN_ABSOLUTE_DEVIATION 通常是近似值。

支持的类型

数字	结果
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
date_nanos	date_nanos
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
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`

编辑

语法

参数

数字
百分位数

描述

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

支持的类型

数字	百分位数	结果
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`

编辑

语法

参数

数字

描述

数值表达式的总和。

支持的类型

数字	结果
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: 要收集最高值的字段。
limit: 要收集的最大值数量。
order: 计算最高值的顺序。可以是 asc 或 desc。

描述

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

支持的类型

field	limit	order	结果
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	keyword

示例

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
date_nanos	date_nanos
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
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`

编辑

语法

参数

数字: 数值。
weight: 数值权重。

描述

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

支持的类型

数字	weight	结果
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 命令支持以下分组函数

BUCKET

`BUCKET`

编辑

语法

参数

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

描述

从日期时间或数字输入创建值组（桶）。桶的大小可以直接提供，也可以根据建议的计数和值范围选择。

支持的类型

field	buckets	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

只要在聚合部分通过在分组部分定义的别名引用该函数，或者使用完全相同的表达式调用该函数，就可以在 STATS … BY … 命令的聚合和分组部分中使用 BUCKET

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	date_nanos	date_nanos	date_nanos
boolean	date_nanos		date_nanos
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	text	keyword
boolean	keyword		keyword
boolean	long	long	long
boolean	long		long
boolean	text	keyword	keyword
boolean	text	text	keyword
boolean	text		keyword
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。

支持的类型

first	rest	结果
boolean	boolean	boolean
boolean		boolean
cartesian_point	cartesian_point	cartesian_point
cartesian_shape	cartesian_shape	cartesian_shape
date	date	date
date_nanos	date_nanos	date_nanos
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	keyword
text		keyword
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
date_nanos	date_nanos	date_nanos
double	double	double
integer	integer	integer
integer		integer
ip	ip	ip
keyword	keyword	keyword
keyword		keyword
long	long	long
long		long
text	text	keyword
text		keyword
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
date_nanos	date_nanos	date_nanos
double	double	double
integer	integer	integer
integer		integer
ip	ip	ip
keyword	keyword	keyword
keyword		keyword
long	long	long
long		long
text	text	keyword
text		keyword
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
date_period	date_nanos	date_nanos
time_duration	date	date
time_duration	date_nanos	date_nanos

示例

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 结合使用以创建日期直方图。例如，每年招聘人数

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`

编辑

语法

参数

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

描述

返回绝对值。

支持的类型

数字	结果
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`

编辑

语法

参数

数字: 介于 -1 和 1 之间的数字。如果为 null，则函数返回 null。

描述

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

支持的类型

数字	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

a:double	acos:double
.9	0.45102681179626236

`ASIN`

编辑

语法

参数

数字: 介于 -1 和 1 之间的数字。如果为 null，则函数返回 null。

描述

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

支持的类型

数字	结果
double	double
integer	double
long	double
unsigned_long	double

示例

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

a:double	asin:double
.9	1.1197695149986342

`ATAN`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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 轴与从原点到笛卡尔平面中点 (x, y) 的射线之间的角度，以弧度表示。

支持的类型

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`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

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

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

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

返回数字的双曲余弦值。

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

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

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

支持的类型

数字	结果
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）。
数字: 数值表达式。如果为 null，则函数返回 null。

描述

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

支持的类型

base	数字	结果
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`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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`

编辑

语法

参数

描述

返回 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`

编辑

语法

参数

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

描述

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

支持的类型

数字	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`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

返回数字的双曲正弦值。

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

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

支持的类型

数字	结果
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`

编辑

语法

参数

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

描述

返回数字的双曲正切值。

支持的类型

数字	结果
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 约束。 MATCH
[预览] 此功能为技术预览版，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 约束。 QSTR

`MATCH`

编辑

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

语法

参数

field: 查询将定向到的字段。
query: 您希望在提供的字段中查找的文本。

描述

在指定字段上执行匹配查询。如果提供的查询与行匹配，则返回 true。

支持的类型

field	query	结果
keyword	keyword	boolean
keyword	text	boolean
text	keyword	boolean
text	text	boolean

示例

FROM books
| WHERE MATCH(author, "Faulkner")
| KEEP book_no, author
| SORT book_no
| LIMIT 5;

book_no:keyword	author:text
2378	[Carol Faulkner, Holly Byers Ochoa, Lucretia Mott]
2713	William Faulkner
2847	Colleen Faulkner
2883	William Faulkner
3293	Danny Faulkner

`QSTR`

编辑

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

语法

参数

query: Lucene 查询字符串格式的查询字符串。

描述

执行查询字符串查询。如果提供的查询字符串与行匹配，则返回 true。

支持的类型

query	结果
keyword	boolean
text	boolean

示例

FROM books
| WHERE QSTR("author: Faulkner")
| KEEP book_no, author
| SORT book_no
| LIMIT 5;

book_no:keyword	author:text
2378	[Carol Faulkner, Holly Byers Ochoa, Lucretia Mott]
2713	William Faulkner
2847	Colleen Faulkner
2883	William Faulkner
3293	Danny Faulkner

ES|QL 空间函数

编辑

ES|QL 支持以下空间函数

`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

abbrev:k	name:text	location:geo_point	city_location:geo_point	distance:d
CPH	哥本哈根	POINT(12.6493508684508 55.6285017221528)	POINT(12.5683 55.6761)	7339.573896618216

`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	荷台达	POINT(42.9511 14.8022)	也门	POINT(42.97109630194 14.7552534413725)	荷台达国际机场	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	airport:text	region:text	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	airport:text	region:text	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	airport:text	region:text	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)

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)

point:geo_point	x:double	y:double
POINT(42.97109629958868 14.7552534006536)	42.97109629958868	14.7552534006536

ES|QL 字符串函数

编辑

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

`BIT_LENGTH`

编辑

语法

参数

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

描述

返回字符串的位长度。

所有字符串均为 UTF-8 编码，因此单个字符可以使用多个字节。

支持的类型

字符串	结果
keyword	integer
text	integer

示例

FROM airports
| WHERE country == "India"
| KEEP city
| EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city)

city:keyword	fn_length:整数	fn_bit_length:整数
Agwār	5	48
艾哈迈达巴德	9	72
班加罗尔	9	72

`BYTE_LENGTH`

编辑

语法

参数

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

描述

返回字符串的字节长度。

所有字符串均为 UTF-8 编码，因此单个字符可以使用多个字节。

支持的类型

字符串	结果
keyword	integer
text	integer

示例

FROM airports
| WHERE country == "India"
| KEEP city
| EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city)

city:keyword	fn_length:整数	fn_byte_length:整数
Agwār	5	6
艾哈迈达巴德	9	9
班加罗尔	9	9

`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	fullname:关键字
Alejandro	McAlpine	Alejandro McAlpine
Amabile	Gomatam	Amabile Gomatam
Anneke	Preusig	Anneke Preusig

`ENDS_WITH`

编辑

语法

参数

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

描述

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

支持的类型

字符串	后缀	结果
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:布尔值
Awdeh	假
Azuma	假
Baek	假
Bamford	真
Bernatsky	假

`FROM_BASE64`

编辑

语法

参数

字符串: Base64 字符串。

描述

解码 Base64 字符串。

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

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

`LEFT`

编辑

语法

参数

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

描述

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

支持的类型

字符串	长度	结果
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:关键字
Awdeh	Awd
Azuma	Azu
Baek	Bae
Bamford	Bam
Bernatsky	Ber

`LENGTH`

编辑

语法

参数

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

描述

返回字符串的字符长度。

所有字符串均为 UTF-8 编码，因此单个字符可以使用多个字节。

支持的类型

字符串	结果
keyword	integer
text	integer

示例

FROM airports
| WHERE country == "India"
| KEEP city
| EVAL fn_length = LENGTH(city)

city:keyword	fn_length:整数
Agwār	5
艾哈迈达巴德	9
班加罗尔	9

`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:整数
你好	3

`LTRIM`

编辑

语法

参数

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

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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:关键字
'some text '	'red '

`REPEAT`

编辑

语法

参数

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

描述

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

支持的类型

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

示例

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

a:关键字	triple_a:关键字
你好！	你好！你好！你好！

`REPLACE`

编辑

语法

参数

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

描述

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

支持的类型

字符串	正则表达式	newString	结果
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:关键字
你好宇宙

`REVERSE`

编辑

语法

参数

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

描述

返回一个新字符串，表示按相反顺序排列的输入字符串。

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

message:keyword	message_reversed:关键字
一些文本	txeT emoS

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

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

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

`RIGHT`

编辑

语法

参数

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

描述

返回从右侧开始从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:关键字
Awdeh	deh
Azuma	uma
Baek	aek
Bamford	ord
Bernatsky	sky

`RTRIM`

编辑

语法

参数

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

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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:关键字
' some text'	' red'

`SPACE`

编辑

语法

参数

数字: 结果中的空格数。

描述

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

支持的类型

数字	结果
integer	keyword

示例

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

message:keyword
你好世界！

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

编辑

语法

参数

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

描述

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

支持的类型

字符串	前缀	结果
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:布尔值
Awdeh	假
Azuma	假
Baek	真
Bamford	真
Bernatsky	真

`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:关键字
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:关键字
Awdeh	deh
Azuma	uma
Baek	aek
Bamford	ord
Bernatsky	sky

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

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

last_name:keyword	ln_sub:关键字
Awdeh	wdeh
Azuma	zuma
Baek	aek
Bamford	amford
Bernatsky	ernatsky

`TO_BASE64`

编辑

语法

参数

字符串: 一个字符串。

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

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

`TO_LOWER`

编辑

语法

参数

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

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

message:keyword	message_lower:关键字
一些文本	一些文本

`TO_UPPER`

编辑

语法

参数

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

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

message:keyword	message_upper:关键字
一些文本	一些文本

`TRIM`

编辑

语法

参数

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

描述

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

支持的类型

字符串	结果
keyword	keyword
text	keyword

示例

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

message:s	color:s
一些文本	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 Point 格式时，才能成功转换。

支持的类型

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:日期时间	y:日期时间	z:日期时间
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
date_nanos	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 值。发生这种情况时，将在响应中添加一个 Warning 标头。该标头将提供有关失败来源的信息

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

以下标头将包含失败原因和违规值

"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_DEGREES`

编辑

语法

参数

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

描述

将一个以弧度为单位的数值转换为度。

支持的类型

数字	结果
double	double
integer	double
long	double
unsigned_long	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_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:keyword	str2:keyword	dbl:double	dbl1:double	dbl2:double
5.20128E11	foo	5.20128E11	5.20128E11	null

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

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

下面的头将包含失败原因和有问题的数值："java.lang.NumberFormatException: For input string: "foo""

`TO_GEOPOINT`

编辑

语法

参数

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

描述

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

支持的类型

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:long	int:integer
[5013792, 2147483647, 501379200000]	[5013792, 2147483647]

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

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

以下标头将包含失败原因和违规值

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

`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:keyword	str2:keyword	ip1:ip	ip2:ip
1.1.1.1	foo	1.1.1.1	null

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

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

以下标头将包含失败原因和违规值

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

`TO_LONG`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
boolean	long
counter_integer	long
counter_long	long
date	long
date_nanos	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:keyword	str2:keyword	str3:keyword	long1:long	long2:long	long3:long
2147483648	2147483648.2	foo	2147483648	2147483648	null

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

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

以下标头将包含失败原因和违规值

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

`TO_RADIANS`

编辑

语法

参数

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

描述

将一个以度为单位的数值转换为弧度。

支持的类型

数字	结果
double	double
integer	double
long	double
unsigned_long	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_STRING`

编辑

语法

参数

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

描述

将输入值转换为字符串。

支持的类型

field	结果
boolean	keyword
cartesian_point	keyword
cartesian_shape	keyword
date	keyword
date_nanos	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_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:日期时间	y:日期时间	z:日期时间
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:keyword	str2:keyword	str3:keyword	long1:unsigned_long	long2:unsigned_long	long3:unsigned_long
2147483648	2147483648.2	foo	2147483648	2147483648	null

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

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

以下标头将包含失败原因和违规值

"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, + "nor "e" notation exponential mark."

`TO_VERSION`

编辑

语法

参数

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

描述

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

支持的类型

field	结果
keyword	version
text	version
version	version

示例

ROW v = TO_VERSION("1.2.3")

v:version
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	keyword
version	version	version

`MV_AVG`

编辑

语法

参数

数字: 多值表达式。

描述

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

支持的类型

数字	结果
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_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: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_COUNT`

编辑

语法

参数

field: 多值表达式。

描述

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

支持的类型

field	结果
boolean	integer
cartesian_point	integer
cartesian_shape	integer
date	integer
date_nanos	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:integer
["foo", "zoo", "bar"]	3

`MV_DEDUPE`

编辑

语法

参数

field: 多值表达式。

描述

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

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

支持的类型

field	结果
boolean	boolean
cartesian_point	cartesian_point
cartesian_shape	cartesian_shape
date	date
date_nanos	date_nanos
double	double
geo_point	geo_point
geo_shape	geo_shape
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
version	version

示例

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

a:关键字	dedupe_a:keyword
["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
date_nanos	date_nanos
double	double
geo_point	geo_point
geo_shape	geo_shape
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
unsigned_long	unsigned_long
version	version

示例

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

a:关键字	first_a:keyword
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
date_nanos	date_nanos
double	double
geo_point	geo_point
geo_shape	geo_shape
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
unsigned_long	unsigned_long
version	version

示例

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

a:关键字	last_a:keyword
foo;bar;baz	"baz"

`MV_MAX`

编辑

语法

参数

field: 多值表达式。

描述

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

支持的类型

field	结果
boolean	boolean
date	date
date_nanos	date_nanos
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
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:关键字	max_a:keyword
["foo", "zoo", "bar"]	"zoo"

`MV_MEDIAN`

编辑

语法

参数

数字: 多值表达式。

描述

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

支持的类型

数字	结果
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_MEDIAN_ABSOLUTE_DEVIATION`

编辑

语法

参数

数字: 多值表达式。

描述

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

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

支持的类型

数字	结果
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
date_nanos	date_nanos
double	double
integer	integer
ip	ip
keyword	keyword
long	long
text	keyword
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_PERCENTILE`

编辑

语法

参数

数字: 多值表达式。
百分位数: 要计算的百分位数。必须是 0 到 100 之间的数字。超出范围的数字将返回 null。

描述

将多值字段转换为包含特定百分比观察值的单值字段。

支持的类型

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

示例

ROW values = [5, 5, 10, 12, 5000]
| EVAL p50 = MV_PERCENTILE(values, 50), median = MV_MEDIAN(values)

values:integer	p50:integer	median:integer
[5, 5, 10, 12, 5000]	10	10

`MV_PSERIES_WEIGHTED_SUM`

编辑

语法

参数

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

描述

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

支持的类型

数字	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
date_nanos	integer	integer	date_nanos
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	keyword
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。
order: 排序顺序。有效选项为 ASC 和 DESC，默认值为 ASC。

描述

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

支持的类型

field	order	结果
boolean	keyword	boolean
date	keyword	date
date_nanos	keyword	date_nanos
double	keyword	double
integer	keyword	integer
ip	keyword	ip
keyword	keyword	keyword
long	keyword	long
text	keyword	keyword
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`

编辑

语法

参数

数字: 多值表达式。

描述

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

支持的类型

数字	结果
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 运算符

编辑

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

二元运算符
一元运算符
逻辑运算符
IS NULL 和 IS NOT NULL 谓词
类型转换 (::)
IN
LIKE
RLIKE
[预览] 此功能为技术预览版，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 约束。搜索运算符

二元运算符

编辑

相等

编辑

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

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

支持的类型

支持的类型

lhs	rhs	结果
boolean	boolean	boolean
cartesian_point	cartesian_point	boolean
cartesian_shape	cartesian_shape	boolean
date	date	boolean
date_nanos	date_nanos	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
date_nanos	date_nanos	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
date_nanos	date_nanos	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
date_nanos	date_nanos	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
date_nanos	date_nanos	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
date_nanos	date_nanos	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 舍入。如果需要浮点除法，请使用 转换 (::) 将其中一个参数转换为 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