Elasticsearch：ES|QL 函數及操作符

如果你對 ES|QL 還不是很熟悉的話，請閱讀之前的文章 “Elasticsearch：ES|QL 查詢語言簡介???????”。ES|QL 提供了一整套用于處理數據的函數和運算符。功能分為以下幾類：

ES|QL 聚合函數

AVG

COUNT

COUNT_DISTINCT

計數為近似值

精度可配置

MAX

MEDIAN

MEDIAN_ABSOLUTE_DEVIATION

MIN

PERCENTILE

PERCENTILE（通常）是近似值

SUM

ES|QL 數學函數

ABS

ACOS

ASIN

ATAN

ATAN2

CEIL

COS

COSH

FLOOR

LOG10

POW

類型規則

算術錯誤

分數指數

支持的輸入和輸出類型表

ROUND

SIN

SINH

SQRT

TAN

TANH

TAU

ES|QL 字符串函數

CONCAT

LEFT

LENGTH

LTRIM

REPLACE

RIGHT

RTRIM

SPLIT

SUBSTRING

TRIM

ES|QL?日期時間函數

AUTO_BUCKET

數字字段

DATE_EXTRACT

DATE_FORMAT

DATE_PARSE

DATE_TRUNC

NOW

ES|QL 類型轉換函數

TO_BOOLEAN

TO_DATETIME

TO_DEGREES

TO_DOUBLE

TO_INTEGER

TO_IP

TO_LONG

TO_RADIANS

TO_STRING

TO_UNSIGNED_LONG

TO_VERSION

ES|QL 條件函數和表達式

CASE

COALESCE

GREATEST

LEAST

ES|QL 多值函數

MV_AVG

MV_CONCAT

MV_COUNT

MV_DEDUPE

MV_MAX

MV_MEDIAN

MV_MIN

MV_SUM

ES|QL 操作符

Binary operators

邏輯運算符

IS NULL 和 IS NOT NULL 謂詞

CIDR_MATCH

ENDS_WITH

IS_FINITE

IS_INFINITE

IS_NAN

RLIKE

STARTS_WITH

ES|QL 聚合函數

STATS ... BY 函數支持以下聚合函數：

AVG
COUNT
COUNT_DISTINCT
MAX
MEDIAN
MEDIAN_ABSOLUTE_DEVIATION
MIN
PERCENTILE
SUM

AVG

數值字段的平均值。

FROM employees
| STATS AVG(height)

AVG(height):double
1.7682

無論輸入類型如何，結果始終是雙精度值。

COUNT

計算字段值。

FROM employees
| STATS COUNT(height)

COUNT(height):long
100

可以采用任何字段類型作為輸入，并且無論輸入類型如何，結果總是 long 類型。

要計算行數，請使用 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

`COUNT_DISTINCT`

獨特值的近似數量。

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

COUNT_DISTINCT(ip0):long	COUNT_DISTINCT(ip1):long
7	8

可以采用任何字段類型作為輸入，并且無論輸入類型如何，結果總是 long 類型。

計數為近似值

計算精確計數需要將值加載到集合中并返回其大小。當處理高基數集和/或大的數據集時，這不會擴展，因為所需的內存使用量以及在節點之間通信這些每個分片集的需要將利用集群的太多資源。

此 COUNT_DISTINCT 函數基于 HyperLogLog++ 算法，該算法基于具有一些有趣屬性的值的哈希值進行計數：

可配置的精度，決定如何用內存換取準確性，
在低基數集上具有出色的準確性，
固定內存使用：無論有數百個還是數十億個唯一值，內存使用僅取決于配置的精度。

對于 c 的精度閾值，我們使用的實現需要大約 c * 8 字節。

下圖顯示了閾值前后誤差的變化情況：

對于所有 3 個閾值，計數均準確至配置的閾值。盡管不能保證，但情況很可能如此。實踐中的準確性取決于所討論的數據集。一般來說，大多數數據集都顯示出一致的良好準確性。另請注意，即使閾值低至 100，即使計算數百萬個項目，誤差仍然非常低（如上圖所示，為 1-6%）。

HyperLogLog++ 算法取決于哈希值的前導零，數據集中哈希值的精確分布會影響基數的準確性。

精度可配置

COUNT_DISTINCT 函數采用可選的第二個參數來配置前面討論的精度。

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

COUNT_DISTINCT(ip0,80000):long	COUNT_DISTINCT(ip1,5):long
7	9

MAX

數字字段的最大值。

FROM employees
| STATS MAX(languages)

MAX(languages):integer
5

MEDIAN

大于所有值一半且小于所有值一半的值，也稱為 50% PERCENTILE。

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

MEDIAN(salary):double	PERCENTILE(salary,50):double
47003	47003

注意：與 ?PERCENTILE 一樣，MEDIAN 通常是近似值。

警告：MEDIAN 也是不確定的（non-deterministic）。這意味著使用相同的數據可能會得到略有不同的結果。

`MEDIAN_ABSOLUTE_DEVIATION`

Median 絕對偏差，變異性的測量。它是一個穩健的統計數據，這意味著它對于描述可能具有異常值或可能不呈正態分布的數據很有用。對于此類數據，它比標準差更具描述性。

它的計算方法是每個數據點與整個樣本中值的偏差的中值。即，對于隨機變量 X，中值絕對偏差為 median(|median(X) - Xi|)。

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

MEDIAN(salary):double	MEDIAN_ABSOLUTE_DEVIATION(salary):double
47003	10096.5

注意：與 PERCENTILE 一樣，MEDIAN_ABSOLUTE_DEVIATION 通常是近似值。

警告：MEDIAN_ABSOLUTE_DEVIATION 也是不確定的（non-disterministic）。這意味著使用相同的數據可能會得到略有不同的結果。

MIN

數值字段的最小值。

FROM employees
| STATS MIN(languages)

MIN(languages):integer
1

`PERCENTILE`

觀察值出現一定百分比時的值。例如，第 95 個百分位數是大于觀測值 95% 的值，第 50 個百分位數是中位數 (MEDIAN)。

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

p0:double	p50:double	p99:double
25324	47003	74970.29

PERCENTILE（通常）是近似值

有許多不同的算法來計算百分位數。簡單的實現只是將所有值存儲在排序數組中。要查找第 50 個百分位數，只需查找 my_array[count(my_array) * 0.5] 處的值即可。

顯然，簡單的實現不會擴展 —— 排序數組隨著數據集中值的數量線性增長。為了計算 Elasticsearch 集群中可能數十億個值的百分位數，需要計算近似百分位數。

百分位數度量使用的算法稱為 TDigest（由 Ted Dunning 在使用 T-Digests 計算準確分位數中介紹）。

使用此指標時，需要牢記一些準則：

準確度與 q(1-q) 成正比。這意味著極端百分位數（例如 99%）比不太極端的百分位數（例如中位數）更準確
對于較小的值集，百分位數非常準確（如果數據足夠小，則可能 100% 準確）。
隨著桶中值數量的增加，算法開始近似百分位數。它實際上是用準確性來換取內存節省。準確的不準確程度很難概括，因為它取決于你的數據分布和聚合的數據量

下圖顯示了均勻分布的相對誤差，具體取決于收集值的數量和請求的百分位數：

它顯示了極端百分位數的精度如何更好。對于大量值，誤差會減小的原因是大數定律使值的分布越來越均勻，并且 t-digest 樹可以更好地進行匯總。如果分布更加傾斜，情況就不會如此。

警告：PERCENTILE 也是不確定的（non-deterministic）。這意味著使用相同的數據可能會得到略有不同的結果。

SUM

數字字段的總和。

FROM employees
| STATS SUM(languages)

SUM(languages):long
281

ES|QL 數學函數

ES|QL 支持這些數學函數：

ABS
ACOS
ASIN
ATAN
ATAN2
CEIL
COS
COSH
E
FLOOR
LOG10
PI
POW
ROUND
SIN
SINH
SQRT
TAN
TANH
TAU

ABS

返回絕對值。

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

支持的類型：

n	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

`ACOS`

語法：

參數：

n:?數字表達。如果為 null，則該函數返回 null。

描述：

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

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

例子：

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


a:double	acos:double
.90.45102681179626236

ASIN

反正弦三角函數。

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

a:double	asin:double
.9	1.1197695149986342

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

ATAN

反正切三角函數。

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

a:double	atan:double
12.9	1.4934316673669235

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

ATAN2

笛卡爾平面中正 x 軸與從原點到點 (x , y) 的射線之間的角度。

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

y:double	x:double	atan2:double
12.9	0.6	1.5243181954438936

支持的類型：

y	x	result
double	double	double
double	integer	double
double	long	double
double	unsigned_long	double
integer	double	double
integer	integer	double
integer	long	double
integer	unsigned_long	double
long	double	double
long	integer	double
long	long	double
long	unsigned_long	double
unsigned_long	double	double
unsigned_long	integer	double
unsigned_long	long	double
unsigned_long	unsigned_long	double

CEIL

將數字向上舍入到最接近的整數。

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

a:double
2

支持的類型：

n	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

COS

余弦三角函數。

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

a:double	cos:double
1.8	-0.2272020946930871

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

COSH

余弦雙曲函數。

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

a:double	cosh:double
1.8	3.1074731763172667

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

E

歐拉數。

ROW E()

E():double
2.718281828459045

FLOOR

將數字向下舍入到最接近的整數。

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

a:double
1

注意：這是長整型（包括無符號）和整數的 noop (no operation, 不做任何處理)。對于雙精度，這會選擇最接近雙精度值的整數（Math.floor）。

支持的類型：

n	result
double	double
integer	integer
long	long
unsigned_long	unsigned_long

LOG10

返回以 10 為底的對數。輸入可以是任何數值，返回值始終是雙精度型。

負數的對數為 NaN。無窮大的對數是無窮大的，就像 0 的對數一樣。

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

d: double	s:double
1000.0	3.0

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

PI

圓的周長與其直徑的比率。

ROW PI()

PI():double
3.141592653589793

POW

返回基數（第一個參數）的指數（第二個參數）次方的值。兩個參數都必須是數字。

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

base:double	exponent:integer	result:double
2.0	2	4.0

類型規則

返回值的類型由底數和指數的類型決定。應用以下規則來確定結果類型：

如果基數或指數中有一個是浮點類型，則結果將為 double
否則，如果基數或指數是 64 位（長整型或無符號長整型），則結果將為 long
否則，結果將是一個 32 位整數（這涵蓋所有其他數字類型，包括 int、short 和 byte）

例如，使用簡單整數作為參數將產生整數結果：

ROW base = 2, exponent = 2
| EVAL s = POW(base, exponent)

base:integer	exponent:integer	s:integer
2	2	4

注意：對于所有情況，實際 pow 函數均使用雙精度值執行。這意味著，對于非常大的非浮點值，該操作導致結果與預期略有不同的可能性很小。然而，非常大的非浮點值更可能的結果是數值溢出。

算術錯誤

算術錯誤和數字溢出不會導致錯誤。相反，結果將為 null，并添加 ArithmeticException 警告。例如：

ROW x = POW(9223372036854775808, 2)

warning:Line 1:9: evaluation of [POW(9223372036854775808, 2)] failed, treating result as null. Only first 20 failures recorded.
warning:Line 1:9: java.lang.ArithmeticException: long overflow

x:long
null

如果需要防止數字溢出，請在任一參數上使用 TO_DOUBLE：

ROW x = POW(9223372036854775808, TO_DOUBLE(1))

x:double
9.223372036854776E18

分數指數

指數可以是分數，這類似于求根。例如，0.5 的指數將給出底數的平方根：

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

base:integer	exponent:double	s:double
4	0.5	2.0

支持的輸入和輸出類型表

為了清楚起見，下表描述了所有數字輸入類型組合的輸出結果類型：

base	exponent	result
double	double	double
double	integer	double
integer	double	double
integer	integer	integer
long	double	double
long	integer	long

ROUND

將數字四舍五入為最接近指定位數的數字。如果未提供位數，則默認為 0 位。如果指定的位數為負數，則四舍五入到小數點左邊的位數。

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

SIN

正弦三角函數。

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

a:double	sin:double
1.8	0.9738476308781951

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

SINH

正弦雙曲函數。

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

a:double	sinh:double
1.8	2.94217428809568

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

SQRT

返回數字的平方根。輸入可以是任何數值，返回值始終是雙精度值。

負數的平方根為 NaN。無窮大的平方根是無窮大。

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

d: double	s:double
100.0	10.0

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

TAN

正切三角函數。

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

a:double	tan:double
1.8	-4.286261674628062

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

TANH

正切雙曲函數。

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

a:double	tanh:double
1.8	0.9468060128462683

支持的類型：

n	result
double	double
integer	double
long	double
unsigned_long	double

TAU

圓的周長與其半徑之比。

ROW TAU()

TAU():double
6.283185307179586

ES|QL 字符串函數

ES|QL 支持以下字符串函數：

CONCAT
LEFT
LENGTH
LTRIM
REPLACE
RIGHT
RTRIM
SPLIT
SUBSTRING
TRIM

CONCAT

連接兩個或多個字符串。

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

LEFT

返回從字符串左側開始提取長度字符的子字符串。

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

last_name:keyword	left:keyword
Awdeh	Awd
Azuma	Azu
Baek	Bae
Bamford	Bam
Bernatsky	Ber

支持的類型：

string	length	result
keyword	integer	keyword

LENGTH

返回字符串的字符長度。

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

LTRIM

從字符串中刪除前導空格。

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

message:keyword	color:keyword
'some text '	'red '

REPLACE

該函數將字符串（第一個參數）中正則表達式（第二個參數）的任何匹配項替換為替換字符串（第三個參數）。

如果任何參數為 NULL，則結果為 NULL。

此示例將出現的單詞 “World” 替換為單詞 “Universe”：

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

str:keyword
Hello Universe

RIGHT

返回從右側開始的字符串中提取 length 字符的子字符串。

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

last_name:keyword	right:keyword
Awdeh	deh
Azuma	uma
Baek	aek
Bamford	ord
Bernatsky	sky

支持的類型:

string	length	result
keyword	integer	keyword

RTRIM

刪除字符串中的尾隨空格。

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

message:keyword	color:keyword
' some text'	' red'

SPLIT

將單個值字符串拆分為多個字符串。例如：

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

將 “foo;bar;baz;qux;quux;corge” 以 ; 進行分割，?并返回一個數組：

words:keyword	word:keyword
foo;bar;baz;qux;quux;corge	[foo,bar,baz,qux,quux,corge]

警告：目前僅支持單字節分隔符。

SUBSTRING

返回字符串的子字符串，由起始位置和可選長度指定。此示例返回每個姓氏的前三個字符：

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

last_name:keyword	ln_sub:keyword
Awdeh	Awd
Azuma	Azu
Baek	Bae
Bamford	Bam
Bernatsky	Ber

負的起始位置被解釋為相對于字符串的結尾。此示例返回每個姓氏的最后三個字符：

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

last_name:keyword	ln_sub:keyword
Awdeh	deh
Azuma	uma
Baek	aek
Bamford	ord
Bernatsky	sky

如果省略 length，則 substring 返回字符串的剩余部分。此示例返回除第一個字符之外的所有字符：

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

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

TRIM

從字符串中刪除前導和尾隨空格。

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

message:s	color:s
some text	red

支持的類型：

arg1	result
keyword	keyword
text	text

ES|QL?日期時間函數

ES|QL 支持以下日期時間函數：

AUTO_BUCKET
DATE_EXTRACT
DATE_FORMAT
DATE_PARSE
DATE_TRUNC
NOW

AUTO_BUCKET

創建人性化的桶并為每行返回與該行所屬的結果桶相對應的日期時間值。將 AUTO_BUCKET 與 STATS ... BY 結合起來創建日期直方圖。

你提供目標桶數量、開始日期和結束日期，它會選擇適當的桶大小來生成目標數量或更少的桶。例如，這要求全年最多 20 個桶，其中選擇每月桶：

ROW date=TO_DATETIME("1985-07-09T00:00:00.000Z")
| EVAL bucket=AUTO_BUCKET(date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")

date:datetime	bucket:datetime
1985-07-09T00:00:00.000Z	1985-07-01T00:00:00.000Z

我們的目標不是提供準確的目標桶數，而是選擇一個人們感到滿意的范圍，最多提供目標桶數。

如果你要求更多的存儲桶，那么 AUTO_BUCKET 可以選擇較小的范圍。例如，一年內最多請求 100 個桶將為你提供一周的桶：

ROW date=TO_DATETIME("1985-07-09T00:00:00.000Z")
| EVAL bucket=AUTO_BUCKET(date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")

date:datetime	bucket:datetime
1985-07-09T00:00:00.000Z	1985-07-08T00:00:00.000Z

AUTO_BUCKET 不過濾任何行。它僅使用提供的時間范圍來選擇合適的桶大小。對于日期超出范圍的行，它返回與范圍之外的存儲桶對應的日期時間。將 AUTO_BUCKET 與 WHERE 結合起來以過濾行。

更完整的示例可能如下所示：

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL bucket = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| STATS AVG(salary) BY bucket
| 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

注意：AUTO_BUCKET 不會創建與任何文檔都不匹配的存儲桶。這就是上面的示例缺少 1985-03-01 和其他日期的原因。

數字字段

auto_bucket 還可以對數字字段進行操作，如下所示：

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL bs = AUTO_BUCKET(salary, 20, 25324, 74999)
| SORT hire_date, salary
| KEEP hire_date, salary, bs

hire_date:date	salary:integer	bs:double
1985-02-18T00:00:00.000Z	66174	65000.0
1985-02-24T00:00:00.000Z	26436	25000.0
1985-05-13T00:00:00.000Z	44817	40000.0
1985-07-09T00:00:00.000Z	62405	60000.0
1985-09-17T00:00:00.000Z	49095	45000.0
1985-10-14T00:00:00.000Z	54329	50000.0
1985-10-20T00:00:00.000Z	48735	45000.0
1985-11-19T00:00:00.000Z	52833	50000.0
1985-11-20T00:00:00.000Z	33956	30000.0
1985-11-20T00:00:00.000Z	74999	70000.0
1985-11-21T00:00:00.000Z	56371	55000.0

與上面的示例不同，你有意在日期范圍上進行過濾，你很少想在數字范圍上進行過濾。所以你必須分別找到最小值和最大值。我們還沒有一種簡單的方法來自動做到這一點。改進即將到來！

DATE_EXTRACT

提取日期的部分內容，例如年、月、日、小時。支持的字段類型是 java.time.temporal.ChronoField 提供的字段類型。

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

DATE_FORMAT

以提供的格式返回日期的字符串表示形式。如果未指定格式，則使用 yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式。

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

DATE_PARSE

語法：

DATE_PARSE([format,] date_string)

參數：

format	日期格式。有關語法，請參閱 DateTimeFormatter 文檔。如果為 null，則該函數返回 null。
date_string	作為字符串的日期表達式。如果為 null 或空字符串，則該函數返回 null。

描述：

通過使用第一個參數中指定的格式解析第二個參數來返回日期。

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

date_string:keyword	date:date
2022-05-06	2022-05-06T00:00:00.000Z

DATE_TRUNC

將日期向下舍入到最接近的間隔。間隔可以使用時間跨度文字語法來表達。

FROM employees
| EVAL year_hired = DATE_TRUNC(1 year, hire_date)
| STATS COUNT(emp_no) BY year_hired
| SORT year_hired

ROW date_string = "2022-05-06"
| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string)
| EVAL year_hired = DATE_TRUNC(1 year, date)
| keep date, year_hired

NOW

返回當前日期和時間。

ROW current_date = NOW()

ES|QL 類型轉換函數

ES|QL 支持以下類型轉換函數：

TO_BOOLEAN
TO_DATETIME
TO_DEGREES
TO_DOUBLE
TO_INTEGER
TO_IP
TO_LONG
TO_RADIANS
TO_STRING
TO_UNSIGNED_LONG
TO_VERSION

TO_BOOLEAN

將輸入值轉換為布爾值。

輸入可以是單值或多值字段或表達式。輸入類型必須是字符串或數字類型。

字符串值 “true” 將不區分大小寫地轉換為布爾值 true。對于其他任何內容，包括空字符串，該函數將返回 false。例如：

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

str:keyword	bool:boolean
["true", "TRuE", "false", "", "yes", "1"]	[true, true, false, false, false, false]

數值 0 將轉換為 false，其他值將轉換為 true。

別名：TO_BOOL

TO_DATETIME

將輸入值轉換為日期值。

輸入可以是單值或多值字段或表達式。輸入類型必須是字符串或數字類型。

僅當字符串遵循 yyyy-MM-dd'T'HH:mm:ss.SSS'Z' 格式時才會成功轉換（要轉換其他格式的日期，請使用 DATE_PARSE）。例如：

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

string:keyword	datetime:date
["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]	[1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z]

請注意，在此示例中，源多值字段中的最后一個值尚未轉換。原因是，如果不遵守日期格式，轉換將導致空值。發生這種情況時，警告標頭將添加到響應中。標頭將提供有關失敗來源的信息：

"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_DT

TO_DEGREES

將弧度數轉換為度數。

輸入可以是單值或多值字段或表達式。輸入類型必須是數字類型，并且結果始終為 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

將輸入值轉換為雙精度值。

輸入可以是單值或多值字段或表達式。輸入類型必須是布爾型、日期型、字符串型或數字型。

例子：

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

請注意，在此示例中，不可能對字符串進行最后一次轉換。發生這種情況時，結果為空值。在這種情況下，警告標頭將添加到響應中。標頭將提供有關失敗來源的信息：

"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\""

如果輸入參數是日期類型，則其值將被解釋為自 Unix 紀元以來的毫秒數，并轉換為雙精度。

布爾值 true 將轉換為 double 1.0， false 則轉換為 0.0。

別名：TO_DBL

TO_INTEGER

將輸入值轉換為整數值。

輸入可以是單值或多值字段或表達式。輸入類型必須是布爾型、日期型、字符串型或數字型。

例子：

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

long:long	int:integer
[5013792, 2147483647, 501379200000]	[5013792, 2147483647]

請注意，在此示例中，多值字段的最后一個值無法轉換為整數。發生這種情況時，結果為空值。在這種情況下，警告標頭將添加到響應中。標頭將提供有關失敗來源的信息：

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

以下標頭將包含失敗原因和違規值：

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

如果輸入參數是日期類型，則其值將被解釋為自 Unix 紀元以來的毫秒數，并轉換為整數。

布爾值 true 將轉換為整數 1， false 將轉換為 0。

別名：TO_INT

TO_IP

將輸入字符串轉換為 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

請注意，在上面的示例中，字符串的最后一次轉換是不可能的。發生這種情況時，結果為空值。在這種情況下，警告標頭將添加到響應中。標頭將提供有關失敗來源的信息：

"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

將輸入值轉換為長整型值。

輸入可以是單值或多值字段或表達式。輸入類型必須是布爾型、日期型、字符串型或數字型。

例子：

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

"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\""

如果輸入參數是日期類型，則其值將被解釋為自 Unix 紀元以來的毫秒數，并轉換為 long。

布爾值 true 將轉換為 long 1， false 將轉換為 0。

`TO_RADIANS`

將度數轉換為弧度。

輸入可以是單值或多值字段或表達式。輸入類型必須是數字類型，并且結果始終為 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

將字段轉換為字符串。例如：

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_STR

支持的類型：

v	result
boolean	keyword
datetime	keyword
double	keyword
integer	keyword
ip	keyword
keyword	keyword
long	keyword
text	keyword
unsigned_long	keyword
version	keyword

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

"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."

如果輸入參數是日期類型，則其值將被解釋為自 Unix 紀元以來的毫秒數，并轉換為 unsigned long。

Boolean true 將轉換為 unsigned long 1， false 則轉換為 0。

別名：TO_ULONG、TO_UL

TO_VERSION

將輸入字符串轉換為版本值。例如：

ROW v = TO_VERSION("1.2.3")

v:version
1.2.3

輸入可以是單值或多值字段或表達式。

別名：TO_VER

支持的類型：

v	result
keyword	version
text	version
version	version

ES|QL 條件函數和表達式

條件函數通過以 if-else 方式求值來返回其參數之一。 ES|QL 支持這些條件函數：

CASE
COALESCE
GREATEST
LEAST

CASE

語法：

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

參數：

conditionX	一個條件
valueX	當相應條件第一個評估為 true 時返回的值。
default_value	沒有條件匹配時返回的默認值。

描述：

接受條件和值對。該函數返回屬于第一個值為 true 的條件的值。

如果參數數量為奇數，則最后一個參數為默認值，當沒有條件匹配時返回該默認值。

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

COALESCE

返回第一個非空值。

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

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

`GREATEST`

返回許多列中的最大值。這與 MV_MAX 類似，只是它旨在一次在多個列上運行。

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

a:integer	b:integer	g:integer
10	20	20

注意：當在 keyword 或 text 字段上運行時，這將按字母順序返回最后一個字符串。當在布爾列上運行時，如果任何值為 true，則返回 true。

支持的類型：

first	rest	result
boolean	boolean	boolean
double	double	double
integer	integer	integer
ip	ip	ip
keyword	keyword	keyword
long	long	long
text	text	text
version	version	version

LEAST

返回許多列中的最小值。這與 MV_MIN 類似，只是它旨在一次在多個列上運行。

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

a:integer	b:integer	l:integer
10	20	10

注意：當在 keyword 或 text 字段上運行時，這將按字母順序返回第一個字符串。當在布爾列上運行時，如果任何值為 false，則返回 false。

支持的類型：

first	rest	result
boolean	boolean	boolean
double	double	double
integer	integer	integer
ip	ip	ip
keyword	keyword	keyword
long	long	long
text	text	text
version	version	version

ES|QL 多值函數

ES|QL 支持以下多值函數：

MV_AVG
MV_CONCAT
MV_COUNT
MV_DEDUPE
MV_MAX
MV_MEDIAN
MV_MIN
MV_SUM

MV_AVG

將多值字段轉換為包含所有值的平均值的單值字段。例如：

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

a:integer	avg_a:double
[3, 5, 1, 6]	3.75

注意：輸出類型始終為 double，輸入類型可以是任意數字。

`MV_CONCAT`

將多值字符串字段轉換為單值字段，其中包含由分隔符分隔的所有值的串聯：

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

a:keyword	j:keyword
["foo", "zoo", "bar"]	"foo, zoo, bar"

如果要連接非字符串字段，請先對它們調用 TO_STRING：

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

a:integer	j:keyword
[10, 9, 8]	"10, 9, 8"

`MV_COUNT`

將多值字段轉換為包含值數量的單值字段：

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

a:keyword	count_a:integer
["foo", "zoo", "bar"]	3

`MV_DEDUPE`

從多值字段中刪除重復項。例如：

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

a:keyword	dedupe_a:keyword
["foo", "foo", "bar", "foo"]	["foo", "bar"]

注意：MV_DEDUPE 可能（但并不總是）對字段中的值進行排序。

`MV_MAX`

將多值字段轉換為包含最大值的單值字段。例如：

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

a:integer	max_a:integer
[3, 5, 1]	5

它可以由任何字段類型使用，包括 keyword 字段。在這種情況下，選擇最后一個字符串，逐字節比較它們的 utf-8 表示形式：

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

a:keyword	max_a:keyword
["foo", "zoo", "bar"]	"zoo"

`MV_MEDIAN`

將多值字段轉換為包含中值的單值字段。例如：

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

將多值字段轉換為包含最小值的單值字段。例如：

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

a:integer	min_a:integer
[2, 1]	1

它可以由任何字段類型使用，包括 keyword 字段。在這種情況下，選擇第一個字符串，逐字節比較它們的 utf-8 表示形式：

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

a:keyword	min_a:keyword
["foo", "bar"]	"bar"

MV_SUM

將多值字段轉換為包含所有值之和的單值字段。例如：

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

a:integer	sum_a:integer
[3, 5, 6]	14

ES|QL 操作符

用于與一個或多個表達式進行比較的布爾運算符。

Binary operators
Logical operators
IS NULL and IS NOT NULL predicates
CIDR_MATCH
ENDS_WITH
IN
IS_FINITE
IS_INFINITE
IS_NAN
LIKE
RLIKE
STARTS_WITH

Binary operators

支持以下二進制比較運算符：

等于：==
不等式：!=
小于：<
小于或等于：<=
大于：>
大于或等于：>=

邏輯運算符

支持以下邏輯運算符：

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

`CIDR_MATCH`

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

CIDR_MATCH 接受兩個或多個參數。第一個參數是 ip 類型的 IP 地址（支持 IPv4 和 IPv6）。后續參數是用于測試 IP 的 CIDR 塊。

FROM hosts
| WHERE CIDR_MATCH(ip, "127.0.0.2/32", "127.0.0.3/32")

`ENDS_WITH`

返回一個布爾值，指示關鍵字字符串是否以另一個字符串結尾：

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

last_name:keyword	ln_E:boolean
Awdeh	false
Azuma	false
Baek	false
Bamford	true
Bernatsky	false

支持的類型：

arg1	arg2	result
keyword	keyword	boolean

IN

IN 運算符允許測試字段或表達式是否等于文字、字段或表達式列表中的元素：

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

`IS_FINITE`

返回一個布爾值，指示其輸入是否是有限數。

ROW d = 1.0
| EVAL s = IS_FINITE(d/0)

`IS_INFINITE`

返回一個布爾值，指示其輸入是否是無限的。

ROW d = 1.0
| EVAL s = IS_INFINITE(d/0)

`IS_NAN`

返回一個布爾值，指示其輸入是否不是數字。

ROW d = 1.0
| EVAL s = IS_NAN(d)

`LIKE`

使用 LIKE 使用通配符根據字符串模式過濾數據。 LIKE 通常作用于位于運算符左側的字段，但它也可以作用于常量（文字）表達式。運算符的右側代表模式。

支持以下通配符：

* 匹配零個或多個字符。
？匹配一個字符。

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

`RLIKE`

使用 RLIKE 使用正則表達式根據字符串模式過濾數據。 RLIKE 通常作用于位于運算符左側的字段，但它也可以作用于常量（文字）表達式。運算符的右側代表模式。

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

`STARTS_WITH`

返回一個布爾值，指示關鍵字字符串是否以另一個字符串開頭：

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

last_name:keyword	ln_S:boolean
Awdeh	false
Azuma	false
Baek	true
Bamford	true
Bernatsky	true

支持的類型：

arg1	arg2	result
keyword	keyword	boolean