內建函式

aes_decrypt(expr, key[, mode[, padding[, aad]]]) - 使用 AES 以 mode 和 padding 解密 expr 的值。支援 16、24 和 32 位元的金鑰長度。支援的 (mode, padding) 組合為 ('ECB', 'PKCS'), ('GCM', 'NONE') 和 ('CBC', 'PKCS')。僅 GCM 支援額外的驗證資料 (AAD)。如果提供用於加密，解密時必須提供相同的 AAD 值。預設模式為 GCM。

引數

expr - 要解密的二進位值。
key - 用於解密資料的密碼。
mode - 指定用於解密訊息的區塊加密模式。有效模式：ECB、GCM、CBC。
padding - 指定如何對長度不是區塊大小倍數的訊息進行填充。有效值：PKCS、NONE、DEFAULT。DEFAULT 填充表示 ECB 的 PKCS、GCM 的 NONE 和 CBC 的 PKCS。
aad - 額外的驗證資料（選用）。僅支援 GCM 模式。這可以是任何自由格式的輸入，且必須同時提供用於加密和解密。

範例

> SELECT aes_decrypt(unhex('83F16B2AA704794132802D248E6BFD4E380078182D1544813898AC97E709B28A94'), '0000111122223333');
 Spark
> SELECT aes_decrypt(unhex('6E7CA17BBB468D3084B5744BCA729FB7B2B7BCB8E4472847D02670489D95FA97DBBA7D3210'), '0000111122223333', 'GCM');
 Spark SQL
> SELECT aes_decrypt(unbase64('3lmwu+Mw0H3fi5NDvcu9lg=='), '1234567890abcdef', 'ECB', 'PKCS');
 Spark SQL
> SELECT aes_decrypt(unbase64('2NYmDCjgXTbbxGA3/SnJEfFC/JQ7olk2VQWReIAAFKo='), '1234567890abcdef', 'CBC');
 Apache Spark
> SELECT aes_decrypt(unbase64('AAAAAAAAAAAAAAAAAAAAAPSd4mWyMZ5mhvjiAPQJnfg='), 'abcdefghijklmnop12345678ABCDEFGH', 'CBC', 'DEFAULT');
 Spark
> SELECT aes_decrypt(unbase64('AAAAAAAAAAAAAAAAQiYi+sTLm7KD9UcZ2nlRdYDe/PX4'), 'abcdefghijklmnop12345678ABCDEFGH', 'GCM', 'DEFAULT', 'This is an AAD mixed into the input');
 Spark

自 3.3.0

aes_encrypt

aes_encrypt(expr, key[, mode[, padding[, iv[, aad]]]]) - 使用 AES 以指定的 mode 和 padding 加密 expr 的值。支援 16、24 和 32 位元的金鑰長度。支援的 (mode, padding) 組合為 ('ECB', 'PKCS'), ('GCM', 'NONE') 和 ('CBC', 'PKCS')。僅 CBC 和 GCM 模式支援初始化向量 (IV)。CBC 的長度必須為 16 位元組，GCM 的長度必須為 12 位元組。如果未提供，將產生一個隨機向量並加到輸出之前。僅 GCM 支援額外的驗證資料 (AAD)。如果提供用於加密，解密時必須提供相同的 AAD 值。預設模式為 GCM。

引數

expr - 要加密的二進位值。
key - 用於加密資料的密碼。
mode - 指定用於加密訊息的區塊加密模式。有效模式：ECB、GCM、CBC。
padding - 指定如何對長度不是區塊大小倍數的訊息進行填充。有效值：PKCS、NONE、DEFAULT。DEFAULT 填充表示 ECB 的 PKCS、GCM 的 NONE 和 CBC 的 PKCS。
iv - 初始化向量（選用）。僅支援 CBC 和 GCM 模式。有效值：無或 ''。CBC 模式的 16 位元組陣列。GCM 模式的 12 位元組陣列。
aad - 額外的驗證資料（選用）。僅支援 GCM 模式。這可以是任何自由格式的輸入，且必須同時提供用於加密和解密。

範例

> SELECT hex(aes_encrypt('Spark', '0000111122223333'));
 83F16B2AA704794132802D248E6BFD4E380078182D1544813898AC97E709B28A94
> SELECT hex(aes_encrypt('Spark SQL', '0000111122223333', 'GCM'));
 6E7CA17BBB468D3084B5744BCA729FB7B2B7BCB8E4472847D02670489D95FA97DBBA7D3210
> SELECT base64(aes_encrypt('Spark SQL', '1234567890abcdef', 'ECB', 'PKCS'));
 3lmwu+Mw0H3fi5NDvcu9lg==
> SELECT base64(aes_encrypt('Apache Spark', '1234567890abcdef', 'CBC', 'DEFAULT'));
 2NYmDCjgXTbbxGA3/SnJEfFC/JQ7olk2VQWReIAAFKo=
> SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop12345678ABCDEFGH', 'CBC', 'DEFAULT', unhex('00000000000000000000000000000000')));
 AAAAAAAAAAAAAAAAAAAAAPSd4mWyMZ5mhvjiAPQJnfg=
> SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop12345678ABCDEFGH', 'GCM', 'DEFAULT', unhex('000000000000000000000000'), 'This is an AAD mixed into the input'));
 AAAAAAAAAAAAAAAAQiYi+sTLm7KD9UcZ2nlRdYDe/PX4

自 3.3.0

aggregate

aggregate(expr, start, merge, finish) - 將二元運算子套用至初始狀態和陣列中的所有元素，並將其簡化為單一狀態。最終狀態會透過套用完成函數轉換為最終結果。

範例

> SELECT aggregate(array(1, 2, 3), 0, (acc, x) -> acc + x);
 6
> SELECT aggregate(array(1, 2, 3), 0, (acc, x) -> acc + x, acc -> acc * 10);
 60

自 2.4.0

and

expr1 and expr2 - 邏輯 AND。

範例

> SELECT true and true;
 true
> SELECT true and false;
 false
> SELECT true and NULL;
 NULL
> SELECT false and NULL;
 false

自 1.0.0

any

any(expr) - 如果 expr 的值中至少有一個為 true，則傳回 true。

範例

> SELECT any(col) FROM VALUES (true), (false), (false) AS tab(col);
 true
> SELECT any(col) FROM VALUES (NULL), (true), (false) AS tab(col);
 true
> SELECT any(col) FROM VALUES (false), (false), (NULL) AS tab(col);
 false

自 3.0.0

any_value

any_value(expr[, isIgnoreNull]) - 傳回群組列中 expr 的某個值。如果 isIgnoreNull 為 true，則只傳回非 Null 值。

範例

> SELECT any_value(col) FROM VALUES (10), (5), (20) AS tab(col);
 10
> SELECT any_value(col) FROM VALUES (NULL), (5), (20) AS tab(col);
 NULL
> SELECT any_value(col, true) FROM VALUES (NULL), (5), (20) AS tab(col);
 5

注意

此函數是非確定性的。

自 3.4.0

approx_count_distinct

approx_count_distinct(expr[, relativeSD]) - 傳回 HyperLogLog++ 估計的基數。relativeSD 定義允許的最大相對標準差。

範例

> SELECT approx_count_distinct(col1) FROM VALUES (1), (1), (2), (2), (3) tab(col1);
 3

自 1.6.0

approx_percentile

approx_percentile(col, percentage [, accuracy]) - 傳回數字或 ansi 區間欄位 col 的近似 百分比，也就是已排序 col 值（從最小到最大）中最小的值，且小於或等於該值 col 值的比例不超過 百分比。百分比的值必須介於 0.0 到 1.0 之間。accuracy 參數（預設值：10000）是一個正數字字面值，用於控制近似精確度，但會犧牲記憶體。accuracy 的值越高，精確度越好，1.0/accuracy 是近似的相對誤差。當 percentage 為陣列時，百分比陣列中的每個值都必須介於 0.0 到 1.0 之間。在此情況下，傳回欄位 col 在給定百分比陣列中的近似百分比陣列。

範例

> SELECT approx_percentile(col, array(0.5, 0.4, 0.1), 100) FROM VALUES (0), (1), (2), (10) AS tab(col);
 [1,1,0]
> SELECT approx_percentile(col, 0.5, 100) FROM VALUES (0), (6), (7), (9), (10) AS tab(col);
 7
> SELECT approx_percentile(col, 0.5, 100) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '1' MONTH), (INTERVAL '2' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-1
> SELECT approx_percentile(col, array(0.5, 0.7), 100) FROM VALUES (INTERVAL '0' SECOND), (INTERVAL '1' SECOND), (INTERVAL '2' SECOND), (INTERVAL '10' SECOND) AS tab(col);
 [0 00:00:01.000000000,0 00:00:02.000000000]

自 2.1.0

array

array(expr, ...) - 傳回包含指定元素的陣列。

範例

> SELECT array(1, 2, 3);
 [1,2,3]

自 1.1.0

array_agg

array_agg(expr) - 收集並傳回非唯一元素的清單。

範例

> SELECT array_agg(col) FROM VALUES (1), (2), (1) AS tab(col);
 [1,2,1]

注意

此函數是非確定性的，因為收集結果的順序取決於列的順序，而列的順序在洗牌後可能會是非確定性的。

自 3.3.0

array_append

array_append(array, element) - 將元素新增到作為第一個引數傳遞的陣列尾端。元素的類型應與陣列元素的類型相似。Null 元素也會附加到陣列中。但如果傳遞的陣列為 NULL，輸出也會為 NULL

範例

> SELECT array_append(array('b', 'd', 'c', 'a'), 'd');
 ["b","d","c","a","d"]
> SELECT array_append(array(1, 2, 3, null), null);
 [1,2,3,null,null]
> SELECT array_append(CAST(null as Array<Int>), 2);
 NULL

自 3.4.0

array_compact

array_compact(array) - 從陣列中移除 Null 值。

範例

> SELECT array_compact(array(1, 2, 3, null));
 [1,2,3]
> SELECT array_compact(array("a", "b", "c"));
 ["a","b","c"]

自 3.4.0

array_contains

array_contains(array, value) - 如果陣列包含該值，則傳回 true。

範例

> SELECT array_contains(array(1, 2, 3), 2);
 true

自 1.5.0

array_distinct

array_distinct(array) - 從陣列中移除重複值。

範例

> SELECT array_distinct(array(1, 2, 3, null, 3));
 [1,2,3,null]

自 2.4.0

array_except

array_except(array1, array2) - 傳回 array1 中但不在 array2 中的元素陣列，且不含重複值。

範例

> SELECT array_except(array(1, 2, 3), array(1, 3, 5));
 [2]

自 2.4.0

array_insert

array_insert(x, pos, val) - 將 val 放入陣列 x 的索引 pos。陣列索引從 1 開始。最大負索引為 -1，函式會在目前最後一個元素之後插入新元素。超過陣列大小的索引會附加陣列，或如果索引為負數，則使用「null」元素在陣列前面加上元素。

範例

> SELECT array_insert(array(1, 2, 3, 4), 5, 5);
 [1,2,3,4,5]
> SELECT array_insert(array(5, 4, 3, 2), -1, 1);
 [5,4,3,2,1]
> SELECT array_insert(array(5, 3, 2, 1), -4, 4);
 [5,4,3,2,1]

自 3.4.0

array_intersect

array_intersect(array1, array2) - 傳回 array1 和 array2 交集中的元素陣列，不含重複值。

範例

> SELECT array_intersect(array(1, 2, 3), array(1, 3, 5));
 [1,3]

自 2.4.0

array_join

array_join(array, delimiter[, nullReplacement]) - 使用分隔符號和一個選用的字串來取代 null 值，串接給定陣列的元素。如果未設定 nullReplacement 的值，則會濾除任何 null 值。

範例

> SELECT array_join(array('hello', 'world'), ' ');
 hello world
> SELECT array_join(array('hello', null ,'world'), ' ');
 hello world
> SELECT array_join(array('hello', null ,'world'), ' ', ',');
 hello , world

自 2.4.0

array_max

array_max(array) - 傳回陣列中的最大值。對於 double/float 類型，NaN 大於任何非 NaN 元素。NULL 元素會被略過。

範例

> SELECT array_max(array(1, 20, null, 3));
 20

自 2.4.0

array_min

array_min(array) - 傳回陣列中的最小值。對於 double/float 類型，NaN 大於任何非 NaN 元素。NULL 元素會被略過。

範例

> SELECT array_min(array(1, 20, null, 3));
 1

自 2.4.0

array_position

array_position(array, element) - 傳回陣列中第一個符合元素的（以 1 為基底的）索引，為 long 型；如果找不到符合的元素，則傳回 0。

範例

> SELECT array_position(array(312, 773, 708, 708), 708);
 3
> SELECT array_position(array(312, 773, 708, 708), 414);
 0

自 2.4.0

array_prepend

array_prepend(array, element) - 將元素新增到作為第一個引數傳遞的陣列的開頭。元素的類型應與陣列元素的類型相同。Null 元素也會被新增到陣列的開頭。但如果傳遞的陣列為 NULL，輸出也會是 NULL

範例

> SELECT array_prepend(array('b', 'd', 'c', 'a'), 'd');
 ["d","b","d","c","a"]
> SELECT array_prepend(array(1, 2, 3, null), null);
 [null,1,2,3,null]
> SELECT array_prepend(CAST(null as Array<Int>), 2);
 NULL

自 3.5.0

array_remove

array_remove(array, element) - 從陣列中移除所有等於 element 的元素。

範例

> SELECT array_remove(array(1, 2, 3, null, 3), 3);
 [1,2,null]

自 2.4.0

array_repeat

array_repeat(element, count) - 傳回包含 element 的陣列，次數為 count。

範例

> SELECT array_repeat('123', 2);
 ["123","123"]

自 2.4.0

array_size

array_size(expr) - 傳回陣列的大小。函式會為 null 輸入傳回 null。

範例

> SELECT array_size(array('b', 'd', 'c', 'a'));
 4

自 3.3.0

array_sort

array_sort(expr, func) - 對輸入陣列進行排序。如果省略 func，則以遞增順序排序。輸入陣列的元素必須可以排序。對於 double/float 類型，NaN 大於任何非 NaN 元素。Null 元素會被置於傳回陣列的結尾。從 3.0.0 開始，此函式也會根據給定的比較器函式對陣列進行排序並傳回。比較器會採用兩個引數，代表陣列的兩個元素。它傳回一個負整數、0 或一個正整數，表示第一個元素小於、等於或大於第二個元素。如果比較器函式傳回 null，則函式會失敗並引發錯誤。

範例

> SELECT array_sort(array(5, 6, 1), (left, right) -> case when left < right then -1 when left > right then 1 else 0 end);
 [1,5,6]
> SELECT array_sort(array('bc', 'ab', 'dc'), (left, right) -> case when left is null and right is null then 0 when left is null then -1 when right is null then 1 when left < right then 1 when left > right then -1 else 0 end);
 ["dc","bc","ab"]
> SELECT array_sort(array('b', 'd', null, 'c', 'a'));
 ["a","b","c","d",null]

自 2.4.0

array_union

array_union(array1, array2) - 傳回 array1 和 array2 聯集的元素陣列，不含重複值。

範例

> SELECT array_union(array(1, 2, 3), array(1, 3, 5));
 [1,2,3,5]

自 2.4.0

arrays_overlap

arrays_overlap(a1, a2) - 如果 a1 至少包含一個非 null 元素，且該元素也存在於 a2 中，則傳回 true。如果陣列沒有共用元素，且兩個陣列都不為空，且其中一個陣列包含 null 元素，則傳回 null，否則傳回 false。

範例

> SELECT arrays_overlap(array(1, 2, 3), array(3, 4, 5));
 true

自 2.4.0

arrays_zip

arrays_zip(a1, a2, ...) - 傳回合併的結構陣列，其中第 N 個結構包含輸入陣列的第 N 個值。

範例

> SELECT arrays_zip(array(1, 2, 3), array(2, 3, 4));
 [{"0":1,"1":2},{"0":2,"1":3},{"0":3,"1":4}]
> SELECT arrays_zip(array(1, 2), array(2, 3), array(3, 4));
 [{"0":1,"1":2,"2":3},{"0":2,"1":3,"2":4}]

自 2.4.0

ascii

ascii(str) - 傳回 str 第一個字元的數字值。

範例

> SELECT ascii('222');
 50
> SELECT ascii(2);
 50

自 1.5.0

asin

asin(expr) - 傳回 expr 的反正弦（又稱反正切），如同 java.lang.Math.asin 所計算的結果。

範例

> SELECT asin(0);
 0.0
> SELECT asin(2);
 NaN

自 1.4.0

asinh

asinh(expr) - 傳回 expr 的反雙曲正弦。

範例

> SELECT asinh(0);
 0.0

自 3.0.0

assert_true

assert_true(expr) - 如果 expr 不為 true，則擲回例外。

範例

> SELECT assert_true(0 < 1);
 NULL

自 2.0.0

atan

atan(expr) - 傳回 expr 的反正切（又稱反正切），如同 java.lang.Math.atan 所計算的結果。

範例

> SELECT atan(0);
 0.0

自 1.4.0

atan2

atan2(exprY, exprX) - 傳回平面正 x 軸與由座標 (exprX, exprY) 指定的點之間的弧度角，如同 java.lang.Math.atan2 所計算的結果。

引數

exprY - y 軸座標
exprX - x 軸座標

範例

> SELECT atan2(0, 0);
 0.0

自 1.4.0

atanh

atanh(expr) - 傳回 expr 的反雙曲正切。

範例

> SELECT atanh(0);
 0.0
> SELECT atanh(2);
 NaN

自 3.0.0

avg

avg(expr) - 傳回從群組值計算的平均值。

範例

> SELECT avg(col) FROM VALUES (1), (2), (3) AS tab(col);
 2.0
> SELECT avg(col) FROM VALUES (1), (2), (NULL) AS tab(col);
 1.5

自 1.0.0

base64

base64(bin) - 將引數從二進位 bin 轉換為 base 64 字串。

範例

> SELECT base64('Spark SQL');
 U3BhcmsgU1FM
> SELECT base64(x'537061726b2053514c');
 U3BhcmsgU1FM

自 1.5.0

between

expr1 [NOT] BETWEEN expr2 AND expr3 - 評估 expr1 是否 [不] 在 expr2 和 expr3 之間。

範例

> SELECT col1 FROM VALUES 1, 3, 5, 7 WHERE col1 BETWEEN 2 AND 5;
 3
 5

自 1.0.0

bigint

bigint(expr) - 將值 expr 轉換為目標資料類型 bigint。

自 2.0.1

bin

bin(expr) - 傳回以二進位表示的長整數值 expr 的字串表示形式。

範例

> SELECT bin(13);
 1101
> SELECT bin(-13);
 1111111111111111111111111111111111111111111111111111111111110011
> SELECT bin(13.3);
 1101

自 1.5.0

binary

binary(expr) - 將值 expr 轉換為目標資料類型 binary。

自 2.0.1

bit_and

bit_and(expr) - 傳回所有非 null 輸入值的按位元 AND，或在沒有非 null 值時傳回 null。

範例

> SELECT bit_and(col) FROM VALUES (3), (5) AS tab(col);
 1

自 3.0.0

bit_count

bit_count(expr) - 傳回引數 expr 中設定的位元數，以未簽署的 64 位元整數表示，或在引數為 NULL 時傳回 NULL。

範例

> SELECT bit_count(0);
 0

自 3.0.0

bit_get

bit_get(expr, pos) - 傳回指定位置的位元值 (0 或 1)。位置從右到左編號，從 0 開始。位置引數不能為負數。

範例

> SELECT bit_get(11, 0);
 1
> SELECT bit_get(11, 2);
 0

自 3.2.0

bit_length

bit_length(expr) - 傳回字串資料的位元長度或二進位資料的位元數。

範例

> SELECT bit_length('Spark SQL');
 72
> SELECT bit_length(x'537061726b2053514c');
 72

自 2.3.0

bit_or

bit_or(expr) - 傳回所有非 null 輸入值的按位元 OR，或在沒有非 null 值時傳回 null。

範例

> SELECT bit_or(col) FROM VALUES (3), (5) AS tab(col);
 7

自 3.0.0

bit_xor

bit_xor(expr) - 傳回所有非 null 輸入值的按位元 XOR，或在沒有非 null 值時傳回 null。

範例

> SELECT bit_xor(col) FROM VALUES (3), (5) AS tab(col);
 6

自 3.0.0

bitmap_bit_position

bitmap_bit_position(child) - 傳回給定輸入子式表達式的位元位置。

範例

> SELECT bitmap_bit_position(1);
 0
> SELECT bitmap_bit_position(123);
 122

自 3.5.0

bitmap_bucket_number

bitmap_bucket_number(child) - 傳回給定輸入子式表達式的區塊號碼。

範例

> SELECT bitmap_bucket_number(123);
 1
> SELECT bitmap_bucket_number(0);
 0

自 3.5.0

bitmap_construct_agg

bitmap_construct_agg(child) - 傳回一個位元圖，其中位元位置由子式表達式的所有值設定。子式表達式很可能是 bitmap_bit_position()。

範例

> SELECT substring(hex(bitmap_construct_agg(bitmap_bit_position(col))), 0, 6) FROM VALUES (1), (2), (3) AS tab(col);
 070000
> SELECT substring(hex(bitmap_construct_agg(bitmap_bit_position(col))), 0, 6) FROM VALUES (1), (1), (1) AS tab(col);
 010000

自 3.5.0

bitmap_count

bitmap_count(child) - 傳回子位元圖中設定的位元數。

範例

> SELECT bitmap_count(X '1010');
 2
> SELECT bitmap_count(X 'FFFF');
 16
> SELECT bitmap_count(X '0');
 0

自 3.5.0

bitmap_or_agg

bitmap_or_agg(child) - 傳回一個位元圖，該位元圖是子式表達式中所有位元圖的按位元 OR。輸入應該是從 bitmap_construct_agg() 建立的位元圖。

範例

> SELECT substring(hex(bitmap_or_agg(col)), 0, 6) FROM VALUES (X '10'), (X '20'), (X '40') AS tab(col);
 700000
> SELECT substring(hex(bitmap_or_agg(col)), 0, 6) FROM VALUES (X '10'), (X '10'), (X '10') AS tab(col);
 100000

自 3.5.0

bool_and

bool_and(expr) - 如果 expr 的所有值都為 true，則傳回 true。

範例

> SELECT bool_and(col) FROM VALUES (true), (true), (true) AS tab(col);
 true
> SELECT bool_and(col) FROM VALUES (NULL), (true), (true) AS tab(col);
 true
> SELECT bool_and(col) FROM VALUES (true), (false), (true) AS tab(col);
 false

自 3.0.0

bool_or

bool_or(expr) - 如果 expr 的至少一個值為 true，則傳回 true。

範例

> SELECT bool_or(col) FROM VALUES (true), (false), (false) AS tab(col);
 true
> SELECT bool_or(col) FROM VALUES (NULL), (true), (false) AS tab(col);
 true
> SELECT bool_or(col) FROM VALUES (false), (false), (NULL) AS tab(col);
 false

自 3.0.0

boolean

boolean(expr) - 將值 expr 轉換成目標資料類型 boolean。

自 2.0.1

bround

bround(expr, d) - 使用 HALF_EVEN 捨入模式，將 expr 捨入到小數點後 d 位。

範例

> SELECT bround(2.5, 0);
 2
> SELECT bround(25, -1);
 20

自 2.0.0

btrim

btrim(str) - 從 str 中移除開頭和結尾的空白字元。

btrim(str, trimStr) - 從 str 中移除開頭和結尾的 trimStr 字元。

引數

str - 字串表達式
trimStr - 要修剪的修剪字串字元，預設值為單一空白

範例

> SELECT btrim('    SparkSQL   ');
 SparkSQL
> SELECT btrim(encode('    SparkSQL   ', 'utf-8'));
 SparkSQL
> SELECT btrim('SSparkSQLS', 'SL');
 parkSQ
> SELECT btrim(encode('SSparkSQLS', 'utf-8'), encode('SL', 'utf-8'));
 parkSQ

自 3.2.0

cardinality

cardinality(expr) - 傳回陣列或映射的大小。如果 spark.sql.legacy.sizeOfNull 設為 false 或 spark.sql.ansi.enabled 設為 true，則函數會傳回 null 的輸入為 null。否則，函數會傳回 null 的輸入為 -1。在預設設定下，函數會傳回 null 的輸入為 -1。

範例

> SELECT cardinality(array('b', 'd', 'c', 'a'));
 4
> SELECT cardinality(map('a', 1, 'b', 2));
 2

自 1.5.0

case

CASE expr1 WHEN expr2 THEN expr3 [WHEN expr4 THEN expr5]* [ELSE expr6] END - 當 expr1 = expr2 時，傳回 expr3；當 expr1 = expr4 時，傳回 expr5；否則傳回 expr6。

引數

expr1 - 作為比較運算元之一的表達式。
expr2、expr4 - 各自作為比較運算元的另一個運算元的表達式。
expr3、expr5、expr6 - 分支值表達式和 else 值表達式都應該是相同類型或可強制轉換成共用類型。

範例

> SELECT CASE col1 WHEN 1 THEN 'one' WHEN 2 THEN 'two' ELSE '?' END FROM VALUES 1, 2, 3;
 one
 two
 ?
> SELECT CASE col1 WHEN 1 THEN 'one' WHEN 2 THEN 'two' END FROM VALUES 1, 2, 3;
 one
 two
 NULL

自 1.0.1

cast

cast(expr AS type) - 將值 expr 轉換成目標資料類型 type。

範例

> SELECT cast('10' as int);
 10

自 1.0.0

cbrt

cbrt(expr) - 傳回 expr 的立方根。

範例

> SELECT cbrt(27.0);
 3.0

自 1.4.0

ceil

ceil(expr[, scale]) - 傳回捨入後不小於 expr 的最小數字。可以指定選用的 scale 參數來控制捨入行為。

範例

> SELECT ceil(-0.1);
 0
> SELECT ceil(5);
 5
> SELECT ceil(3.1411, 3);
 3.142
> SELECT ceil(3.1411, -3);
 1000

自 3.3.0

ceiling

ceiling(expr[, scale]) - 傳回捨入後不小於 expr 的最小數字。可以指定選用的 scale 參數來控制捨入行為。

範例

> SELECT ceiling(-0.1);
 0
> SELECT ceiling(5);
 5
> SELECT ceiling(3.1411, 3);
 3.142
> SELECT ceiling(3.1411, -3);
 1000

自 3.3.0

char

char(expr) - 傳回二進位等同於 expr 的 ASCII 字元。如果 n 大於 256，則結果等同於 chr(n % 256)

範例

> SELECT char(65);
 A

自 2.3.0

char_length

char_length(expr) - 傳回字串資料的字元長度或二進位資料的位元組數。字串資料的長度包括尾隨空白。二進位資料的長度包括二進位零。

範例

> SELECT char_length('Spark SQL ');
 10
> SELECT char_length(x'537061726b2053514c');
 9
> SELECT CHAR_LENGTH('Spark SQL ');
 10
> SELECT CHARACTER_LENGTH('Spark SQL ');
 10

自 1.5.0

character_length

character_length(expr) - 傳回字串資料的字元長度或二進位資料的位元組數。字串資料的長度包含尾隨空白。二進位資料的長度包含二進位零。

範例

> SELECT character_length('Spark SQL ');
 10
> SELECT character_length(x'537061726b2053514c');
 9
> SELECT CHAR_LENGTH('Spark SQL ');
 10
> SELECT CHARACTER_LENGTH('Spark SQL ');
 10

自 1.5.0

chr

chr(expr) - 傳回具有等於 expr 的二進位對應的 ASCII 字元。如果 n 大於 256，結果等於 chr(n % 256)

範例

> SELECT chr(65);
 A

自 2.3.0

coalesce

coalesce(expr1, expr2, ...) - 傳回第一個非 Null 參數（如果存在）。否則傳回 Null。

範例

> SELECT coalesce(NULL, 1, NULL);
 1

自 1.0.0

collect_list

collect_list(expr) - 收集並傳回非唯一元素的清單。

範例

> SELECT collect_list(col) FROM VALUES (1), (2), (1) AS tab(col);
 [1,2,1]

注意

此函數是非確定性的，因為收集結果的順序取決於列的順序，而列的順序在洗牌後可能會是非確定性的。

自 2.0.0

collect_set

collect_set(expr) - 收集並傳回唯一元素的集合。

範例

> SELECT collect_set(col) FROM VALUES (1), (2), (1) AS tab(col);
 [1,2]

注意

此函數是非確定性的，因為收集結果的順序取決於列的順序，而列的順序在洗牌後可能會是非確定性的。

自 2.0.0

concat

concat(col1, col2, ..., colN) - 傳回 col1、col2、...、colN 的串接。

範例

> SELECT concat('Spark', 'SQL');
 SparkSQL
> SELECT concat(array(1, 2, 3), array(4, 5), array(6));
 [1,2,3,4,5,6]

注意

陣列的串接邏輯自 2.4.0 起可用。

自 1.5.0

concat_ws

concat_ws(sep[, str | array(str)]+) - 傳回以 sep 分隔的字串的串接，略過 Null 值。

範例

> SELECT concat_ws(' ', 'Spark', 'SQL');
  Spark SQL
> SELECT concat_ws('s');

> SELECT concat_ws('/', 'foo', null, 'bar');
  foo/bar
> SELECT concat_ws(null, 'Spark', 'SQL');
  NULL

自 1.5.0

contains

contains(left, right) - 傳回布林值。如果 right 在 left 中找到，則值為 True。如果任一輸入表達式為 NULL，則傳回 NULL。否則傳回 False。left 或 right 都必須為字串或二進位類型。

範例

> SELECT contains('Spark SQL', 'Spark');
 true
> SELECT contains('Spark SQL', 'SPARK');
 false
> SELECT contains('Spark SQL', null);
 NULL
> SELECT contains(x'537061726b2053514c', x'537061726b');
 true

自 3.3.0

conv

conv(num, from_base, to_base) - 將 num 從 from_base 轉換為 to_base。

範例

> SELECT conv('100', 2, 10);
 4
> SELECT conv(-10, 16, -10);
 -16

自 1.5.0

convert_timezone

convert_timezone([sourceTz, ]targetTz, sourceTs) - 將沒有時區的時間戳記 sourceTs 從 sourceTz 時區轉換為 targetTz。

引數

sourceTz - 輸入時間戳記的時區。如果遺漏，則使用目前的階段時區作為來源時區。
targetTz - 應將輸入時間戳記轉換到的時區
sourceTs - 沒有時區的時間戳記

範例

> SELECT convert_timezone('Europe/Brussels', 'America/Los_Angeles', timestamp_ntz'2021-12-06 00:00:00');
 2021-12-05 15:00:00
> SELECT convert_timezone('Europe/Brussels', timestamp_ntz'2021-12-05 15:00:00');
 2021-12-06 00:00:00

自 3.4.0

corr

corr(expr1, expr2) - 傳回一組數字對之間的皮爾森相關係數。

範例

> SELECT corr(c1, c2) FROM VALUES (3, 2), (3, 3), (6, 4) as tab(c1, c2);
 0.8660254037844387

自 1.6.0

cos

cos(expr) - 傳回 expr 的餘弦，就像由 java.lang.Math.cos 計算的一樣。

引數

expr - 以弧度為單位的角度

範例

> SELECT cos(0);
 1.0

自 1.4.0

cosh

cosh(expr) - 傳回 expr 的雙曲餘弦，就像由 java.lang.Math.cosh 計算的一樣。

引數

expr - 雙曲角度

範例

> SELECT cosh(0);
 1.0

自 1.4.0

cot

cot(expr) - 傳回 expr 的餘切，就像由 1/java.lang.Math.tan 計算的一樣。

引數

expr - 以弧度為單位的角度

範例

> SELECT cot(1);
 0.6420926159343306

自 2.3.0

count

count(*) - 傳回已擷取列的總數，包括包含 Null 的列。

count(expr[, expr...]) - 傳回所有提供表達式皆非 NULL 的列數。

count(DISTINCT expr[, expr...]) - 傳回所有提供表達式皆唯一且非 NULL 的列數。

範例

> SELECT count(*) FROM VALUES (NULL), (5), (5), (20) AS tab(col);
 4
> SELECT count(col) FROM VALUES (NULL), (5), (5), (20) AS tab(col);
 3
> SELECT count(DISTINCT col) FROM VALUES (NULL), (5), (5), (10) AS tab(col);
 2

自 1.0.0

count_if

count_if(expr) - 傳回表達式的 TRUE 值數。

範例

> SELECT count_if(col % 2 = 0) FROM VALUES (NULL), (0), (1), (2), (3) AS tab(col);
 2
> SELECT count_if(col IS NULL) FROM VALUES (NULL), (0), (1), (2), (3) AS tab(col);
 1

自 3.0.0

count_min_sketch

count_min_sketch(col, eps, confidence, seed) - 傳回具有給定 eps、信心度和種子的欄位計數最小草圖。結果為位元組陣列，在使用前可反序列化為 CountMinSketch。計數最小草圖是一種機率資料結構，用於使用次線性空間進行基數估計。

範例

> SELECT hex(count_min_sketch(col, 0.5d, 0.5d, 1)) FROM VALUES (1), (2), (1) AS tab(col);
 0000000100000000000000030000000100000004000000005D8D6AB90000000000000000000000000000000200000000000000010000000000000000

自 2.2.0

covar_pop

covar_pop(expr1, expr2) - 傳回一組數字配對的總體共變異數。

範例

> SELECT covar_pop(c1, c2) FROM VALUES (1,1), (2,2), (3,3) AS tab(c1, c2);
 0.6666666666666666

自 2.0.0

covar_samp

covar_samp(expr1, expr2) - 傳回一組數字配對的樣本共變異數。

範例

> SELECT covar_samp(c1, c2) FROM VALUES (1,1), (2,2), (3,3) AS tab(c1, c2);
 1.0

自 2.0.0

crc32

crc32(expr) - 傳回 expr 的循環冗餘檢查值，為 bigint。

範例

> SELECT crc32('Spark');
 1557323817

自 1.5.0

csc

csc(expr) - 傳回 expr 的餘割，如同由 1/java.lang.Math.sin 計算。

引數

expr - 以弧度為單位的角度

範例

> SELECT csc(1);
 1.1883951057781212

自 3.3.0

cume_dist

cume_dist() - 計算值在分割中所有值中的位置。

範例

> SELECT a, b, cume_dist() OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   0.6666666666666666
 A1 1   0.6666666666666666
 A1 2   1.0
 A2 3   1.0

自 2.0.0

curdate

curdate() - 傳回查詢評估開始時的當前日期。同一查詢中的所有 curdate 呼叫都會傳回相同的值。

範例

> SELECT curdate();
 2022-09-06

自 3.4.0

current_catalog

current_catalog() - 傳回目前的目錄。

範例

> SELECT current_catalog();
 spark_catalog

自 3.1.0

current_database

current_database() - 傳回目前的資料庫。

範例

> SELECT current_database();
 default

自 1.6.0

current_date

current_date() - 傳回查詢評估開始時的當前日期。同一查詢中的所有 current_date 呼叫都會傳回相同的值。

current_date - 傳回查詢評估開始時的當前日期。

範例

> SELECT current_date();
 2020-04-25
> SELECT current_date;
 2020-04-25

注意

自 2.0.1 起，支援沒有大括號的語法。

自 1.5.0

current_schema

current_schema() - 傳回目前的資料庫。

範例

> SELECT current_schema();
 default

自 1.6.0

current_timestamp

current_timestamp() - 傳回查詢評估開始時的當前時間戳記。同一查詢中的所有 current_timestamp 呼叫都會傳回相同的值。

current_timestamp - 傳回查詢評估開始時的當前時間戳記。

範例

> SELECT current_timestamp();
 2020-04-25 15:49:11.914
> SELECT current_timestamp;
 2020-04-25 15:49:11.914

注意

自 2.0.1 起，支援沒有大括號的語法。

自 1.5.0

current_timezone

current_timezone() - 傳回目前的時區。

範例

> SELECT current_timezone();
 Asia/Shanghai

自 3.1.0

current_user

current_user() - 目前執行內容的使用者名稱。

範例

> SELECT current_user();
 mockingjay

自 3.2.0

date

date(expr) - 將值 expr 轉換為目標資料類型 date。

自 2.0.1

date_add

date_add(start_date, num_days) - 傳回在 start_date 之後 num_days 的日期。

範例

> SELECT date_add('2016-07-30', 1);
 2016-07-31

自 1.5.0

date_diff

date_diff(endDate, startDate) - 傳回從 startDate 到 endDate 的天數。

範例

> SELECT date_diff('2009-07-31', '2009-07-30');
 1

> SELECT date_diff('2009-07-30', '2009-07-31');
 -1

自 3.4.0

date_format

date_format(timestamp, fmt) - 將 timestamp 轉換為日期格式 fmt 所指定的字串值。

引數

時間戳記 - 要轉換為給定格式的日期/時間戳記或字串。
fmt - 要遵循的日期/時間格式模式。有關有效的日期和時間格式模式，請參閱日期時間模式。

範例

> SELECT date_format('2016-04-08', 'y');
 2016

自 1.5.0

date_from_unix_date

date_from_unix_date(days) - 從 1970-01-01 以來的日數建立日期。

範例

> SELECT date_from_unix_date(1);
 1970-01-02

自 3.1.0

date_part

date_part(field, source) - 萃取日期/時間戳記或區間來源的一部分。

引數

field - 選擇來源的哪一部分應萃取，且支援的字串值與等效函數 EXTRACT 的欄位相同。
source - 應從中萃取 field 的日期/時間戳記或區間欄位

範例

> SELECT date_part('YEAR', TIMESTAMP '2019-08-12 01:00:00.123456');
 2019
> SELECT date_part('week', timestamp'2019-08-12 01:00:00.123456');
 33
> SELECT date_part('doy', DATE'2019-08-12');
 224
> SELECT date_part('SECONDS', timestamp'2019-10-01 00:00:01.000001');
 1.000001
> SELECT date_part('days', interval 5 days 3 hours 7 minutes);
 5
> SELECT date_part('seconds', interval 5 hours 30 seconds 1 milliseconds 1 microseconds);
 30.001001
> SELECT date_part('MONTH', INTERVAL '2021-11' YEAR TO MONTH);
 11
> SELECT date_part('MINUTE', INTERVAL '123 23:55:59.002001' DAY TO SECOND);
 55

注意

date_part 函數等同於 SQL 標準函數 EXTRACT(field FROM source)

自 3.0.0

date_sub

date_sub(start_date, num_days) - 傳回在 start_date 之前 num_days 的日期。

範例

> SELECT date_sub('2016-07-30', 1);
 2016-07-29

自 1.5.0

date_trunc

date_trunc(fmt, ts) - 傳回時間戳記 ts，已根據格式模式 fmt 指定的單位進行截斷。

引數

fmt - 代表要截斷到的單位的格式
- "YEAR", "YYYY", "YY" - 截斷到 ts 所屬年份的第一個日期，時間部分將歸零
- "QUARTER" - 截斷到 ts 所屬季度的第一個日期，時間部分將歸零
- "MONTH", "MM", "MON" - 截斷到 ts 所屬月份的第一個日期，時間部分將歸零
- "WEEK" - 截斷到 ts 所屬週的星期一，時間部分將歸零
- "DAY", "DD" - 將時間部分歸零
- "HOUR" - 將分鐘和秒數（含小數部分）歸零
- "MINUTE"- 將秒數（含小數部分）歸零
- "SECOND" - 將秒數小數部分歸零
- "MILLISECOND" - 將微秒歸零
- "MICROSECOND" - 維持所有內容
ts - 日期時間值或有效的時間戳記字串

範例

> SELECT date_trunc('YEAR', '2015-03-05T09:32:05.359');
 2015-01-01 00:00:00
> SELECT date_trunc('MM', '2015-03-05T09:32:05.359');
 2015-03-01 00:00:00
> SELECT date_trunc('DD', '2015-03-05T09:32:05.359');
 2015-03-05 00:00:00
> SELECT date_trunc('HOUR', '2015-03-05T09:32:05.359');
 2015-03-05 09:00:00
> SELECT date_trunc('MILLISECOND', '2015-03-05T09:32:05.123456');
 2015-03-05 09:32:05.123

自 2.3.0

dateadd

dateadd(start_date, num_days) - 傳回在 start_date 之後 num_days 的日期。

範例

> SELECT dateadd('2016-07-30', 1);
 2016-07-31

自 3.4.0

datediff

datediff(endDate, startDate) - 傳回從 startDate 到 endDate 的天數。

範例

> SELECT datediff('2009-07-31', '2009-07-30');
 1

> SELECT datediff('2009-07-30', '2009-07-31');
 -1

自 1.5.0

datepart

datepart(field, source) - 萃取日期/時間戳記或區間來源的一部分。

引數

field - 選擇來源的哪一部分應萃取，且支援的字串值與等效函數 EXTRACT 的欄位相同。
source - 應從中萃取 field 的日期/時間戳記或區間欄位

範例

> SELECT datepart('YEAR', TIMESTAMP '2019-08-12 01:00:00.123456');
 2019
> SELECT datepart('week', timestamp'2019-08-12 01:00:00.123456');
 33
> SELECT datepart('doy', DATE'2019-08-12');
 224
> SELECT datepart('SECONDS', timestamp'2019-10-01 00:00:01.000001');
 1.000001
> SELECT datepart('days', interval 5 days 3 hours 7 minutes);
 5
> SELECT datepart('seconds', interval 5 hours 30 seconds 1 milliseconds 1 microseconds);
 30.001001
> SELECT datepart('MONTH', INTERVAL '2021-11' YEAR TO MONTH);
 11
> SELECT datepart('MINUTE', INTERVAL '123 23:55:59.002001' DAY TO SECOND);
 55

注意

datepart 函數等同於 SQL 標準函數 EXTRACT(field FROM source)

自 3.4.0

day

day(date) - 傳回日期/時間戳記的月份中的日期。

範例

> SELECT day('2009-07-30');
 30

自 1.5.0

dayofmonth

dayofmonth(date) - 傳回日期/時間戳記的月份中的日期。

範例

> SELECT dayofmonth('2009-07-30');
 30

自 1.5.0

dayofweek

dayofweek(date) - 傳回日期/時間戳記的星期（1 = 星期日，2 = 星期一，...，7 = 星期六）。

範例

> SELECT dayofweek('2009-07-30');
 5

自 2.3.0

dayofyear

dayofyear(date) - 傳回日期/時間戳記的年度中的日期。

範例

> SELECT dayofyear('2016-04-09');
 100

自 1.5.0

decimal

decimal(expr) - 將值 expr 轉換為目標資料類型 decimal。

自 2.0.1

decode

decode(bin, charset) - 使用第二個參數字元集解碼第一個參數。

decode(expr, search, result [, search, result ] ... [, default]) - 依序將 expr 與每個 search 值進行比較。如果 expr 等於某個 search 值，decode 會傳回對應的 result。如果找不到符合的項目，則傳回 default。如果省略 default，則傳回 null。

範例

> SELECT decode(encode('abc', 'utf-8'), 'utf-8');
 abc
> SELECT decode(2, 1, 'Southlake', 2, 'San Francisco', 3, 'New Jersey', 4, 'Seattle', 'Non domestic');
 San Francisco
> SELECT decode(6, 1, 'Southlake', 2, 'San Francisco', 3, 'New Jersey', 4, 'Seattle', 'Non domestic');
 Non domestic
> SELECT decode(6, 1, 'Southlake', 2, 'San Francisco', 3, 'New Jersey', 4, 'Seattle');
 NULL
> SELECT decode(null, 6, 'Spark', NULL, 'SQL', 4, 'rocks');
 SQL

自 3.2.0

degrees

degrees(expr) - 將弧度轉換為角度。

引數

expr - 以弧度為單位的角度

範例

> SELECT degrees(3.141592653589793);
 180.0

自 1.4.0

dense_rank

dense_rank() - 計算一組值中某個值的名次。結果為先前指定的排名值再加一。與 rank 函數不同，dense_rank 在排名順序中不會產生間隔。

引數

children - 用於作為排名基礎；children 中的一個值變更會觸發排名變更。這是一個內部參數，由分析器指定。

範例

> SELECT a, b, dense_rank(b) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   1
 A1 2   2
 A2 3   1

自 2.0.0

div

expr1 div expr2 - 將 expr1 除以 expr2。如果某個運算元為 NULL 或 expr2 為 0，則傳回 NULL。結果會轉換為 long。

範例

> SELECT 3 div 2;
 1
> SELECT INTERVAL '1-1' YEAR TO MONTH div INTERVAL '-1' MONTH;
 -13

自 3.0.0

double

double(expr) - 將值 expr 轉換為目標資料類型 double。

自 2.0.1

e

e() - 傳回歐拉數 e。

範例

> SELECT e();
 2.718281828459045

自 1.5.0

element_at

element_at(array, index) - 傳回陣列中位於指定 (以 1 為基底) index 的元素。如果 Index 為 0，Spark 會擲回錯誤。如果 index < 0，則從最後一個元素存取到第一個元素。如果 index 超過陣列長度，且 spark.sql.ansi.enabled 設為 false，則函數會傳回 NULL。如果 spark.sql.ansi.enabled 設為 true，則會對無效的 index 擲回 ArrayIndexOutOfBoundsException。

element_at(map, key) - 傳回指定 key 的值。如果 map 中不包含該 key，則函數會傳回 NULL。

範例

> SELECT element_at(array(1, 2, 3), 2);
 2
> SELECT element_at(map(1, 'a', 2, 'b'), 2);
 b

自 2.4.0

elt

elt(n, input1, input2, ...) - 傳回第 n 個輸入，例如當 n 為 2 時，傳回 input2。如果 index 超過陣列長度，且 spark.sql.ansi.enabled 設為 false，則函數會傳回 NULL。如果 spark.sql.ansi.enabled 設為 true，則會對無效的 index 擲回 ArrayIndexOutOfBoundsException。

範例

> SELECT elt(1, 'scala', 'java');
 scala
> SELECT elt(2, 'a', 1);
 1

自 2.0.0

encode

encode(str, charset) - 使用第二個參數的字元集對第一個參數進行編碼。

範例

> SELECT encode('abc', 'utf-8');
 abc

自 1.5.0

endswith

endswith(left, right) - 傳回布林值。如果 left 以 right 結尾，則值為 True。如果任一輸入表達式為 NULL，則傳回 NULL。否則，傳回 False。left 或 right 都必須為字串或二進位類型。

範例

> SELECT endswith('Spark SQL', 'SQL');
 true
> SELECT endswith('Spark SQL', 'Spark');
 false
> SELECT endswith('Spark SQL', null);
 NULL
> SELECT endswith(x'537061726b2053514c', x'537061726b');
 false
> SELECT endswith(x'537061726b2053514c', x'53514c');
 true

自 3.3.0

equal_null

equal_null(expr1, expr2) - 對於非 NULL 參數，傳回與 EQUAL(=) 算子相同結果，但如果兩者都為 null，則傳回 true，如果其中一個為 null，則傳回 false。

引數

expr1、expr2 - 這兩個表達式必須是相同類型，或可以轉換成共用類型，而且必須是可以使用等式比較運算的類型。不支援 Map 類型。對於陣列/結構等複雜類型，欄位的資料類型必須是可以排序的。

範例

> SELECT equal_null(3, 3);
 true
> SELECT equal_null(1, '11');
 false
> SELECT equal_null(true, NULL);
 false
> SELECT equal_null(NULL, 'abc');
 false
> SELECT equal_null(NULL, NULL);
 true

自 3.4.0

every

every(expr) - 如果 expr 的所有值都為 true，則傳回 true。

範例

> SELECT every(col) FROM VALUES (true), (true), (true) AS tab(col);
 true
> SELECT every(col) FROM VALUES (NULL), (true), (true) AS tab(col);
 true
> SELECT every(col) FROM VALUES (true), (false), (true) AS tab(col);
 false

自 3.0.0

exists

exists(expr, pred) - 測試一個謂詞是否對陣列中的一個或多個元素成立。

範例

> SELECT exists(array(1, 2, 3), x -> x % 2 == 0);
 true
> SELECT exists(array(1, 2, 3), x -> x % 2 == 10);
 false
> SELECT exists(array(1, null, 3), x -> x % 2 == 0);
 NULL
> SELECT exists(array(0, null, 2, 3, null), x -> x IS NULL);
 true
> SELECT exists(array(1, 2, 3), x -> x IS NULL);
 false

自 2.4.0

exp

exp(expr) - 傳回 e 的 expr 次方。

範例

> SELECT exp(0);
 1.0

自 1.4.0

explode

explode(expr) - 將陣列 expr 的元素分隔成多列，或將映射 expr 的元素分隔成多列和多欄。除非另有指定，否則對陣列的元素使用預設欄位名稱 col，對映射的元素使用 key 和 value。

範例

> SELECT explode(array(10, 20));
 10
 20
> SELECT explode(collection => array(10, 20));
 10
 20
> SELECT * FROM explode(collection => array(10, 20));
 10
 20

自 1.0.0

explode_outer

explode_outer(expr) - 將陣列 expr 的元素分隔成多列，或將映射 expr 的元素分隔成多列和多欄。除非另有指定，否則對陣列的元素使用預設欄位名稱 col，對映射的元素使用 key 和 value。

範例

> SELECT explode_outer(array(10, 20));
 10
 20
> SELECT explode_outer(collection => array(10, 20));
 10
 20
> SELECT * FROM explode_outer(collection => array(10, 20));
 10
 20

自 1.0.0

expm1

expm1(expr) - 傳回 exp(expr) - 1。

範例

> SELECT expm1(0);
 0.0

自 1.4.0

extract

extract(field FROM source) - 從日期/時間戳記或區間來源中提取一部分。

引數

field - 選擇要從來源中提取哪一部分
- field 的日期和時間戳記的支援字串值（不區分大小寫）
  - "YEAR", ("Y", "YEARS", "YR", "YRS") - 年份欄位
  - "YEAROFWEEK" - 日期時間落在的 ISO 8601 週編號年。例如，2005-01-02 是 2004 年的第 53 週的一部分，因此結果為 2004
  - "QUARTER", ("QTR") - 日期時間落在的年份的季度 (1 - 4)
  - "MONTH", ("MON", "MONS", "MONTHS") - 月份欄位 (1 - 12)
  - "WEEK", ("W", "WEEKS") - ISO 8601 週數週為基礎年的週數。週被認為從星期一開始，第 1 週是具有 >3 天的第一週。在 ISO 週編號系統中，1 月初的日期可能屬於前一年的第 52 週或第 53 週，而 12 月末的日期可能屬於下一年的第一週。例如，2005-01-02 是 2004 年的第 53 週的一部分，而 2012-12-31 是 2013 年的第一週的一部分
  - "DAY", ("D", "DAYS") - 月份欄位的日期 (1 - 31)
  - "DAYOFWEEK",("DOW") - 日期時間的星期，星期日 (1) 到星期六 (7)
  - "DAYOFWEEK_ISO",("DOW_ISO") - ISO 8601 為基礎的日期時間星期，星期一 (1) 至星期日 (7)
  - "DOY" - 一年中的第幾天 (1 - 365/366)
  - "HOUR", ("H", "HOURS", "HR", "HRS") - 小時欄位 (0 - 23)
  - "MINUTE", ("M", "MIN", "MINS", "MINUTES") - 分鐘欄位 (0 - 59)
  - "SECOND", ("S", "SEC", "SECONDS", "SECS") - 秒數欄位，包含小數部分
- field 的支援字串值為間隔 (包含 months、days、microseconds)，且不分大小寫
  - "YEAR", ("Y", "YEARS", "YR", "YRS") - 總計 months / 12
  - "MONTH", ("MON", "MONS", "MONTHS") - 總計 months % 12
  - "DAY", ("D", "DAYS") - 間隔的 days 部分
  - "HOUR", ("H", "HOURS", "HR", "HRS") - microseconds 包含多少小時
  - "MINUTE", ("M", "MIN", "MINS", "MINUTES") - 從 microseconds 取出小時後剩餘的分鐘數
  - "SECOND", ("S", "SEC", "SECONDS", "SECS") - 從 microseconds 取出小時和分鐘後剩餘的秒數，包含小數部分
source - 應從中萃取 field 的日期/時間戳記或區間欄位

範例

> SELECT extract(YEAR FROM TIMESTAMP '2019-08-12 01:00:00.123456');
 2019
> SELECT extract(week FROM timestamp'2019-08-12 01:00:00.123456');
 33
> SELECT extract(doy FROM DATE'2019-08-12');
 224
> SELECT extract(SECONDS FROM timestamp'2019-10-01 00:00:01.000001');
 1.000001
> SELECT extract(days FROM interval 5 days 3 hours 7 minutes);
 5
> SELECT extract(seconds FROM interval 5 hours 30 seconds 1 milliseconds 1 microseconds);
 30.001001
> SELECT extract(MONTH FROM INTERVAL '2021-11' YEAR TO MONTH);
 11
> SELECT extract(MINUTE FROM INTERVAL '123 23:55:59.002001' DAY TO SECOND);
 55

注意

extract 函數等同於 date_part(field, source)。

自 3.0.0

factorial

factorial(expr) - 傳回 expr 的階乘。expr 為 [0..20]。否則為 null。

範例

> SELECT factorial(5);
 120

自 1.5.0

filter

filter(expr, func) - 使用指定的謂詞篩選輸入陣列。

範例

> SELECT filter(array(1, 2, 3), x -> x % 2 == 1);
 [1,3]
> SELECT filter(array(0, 2, 3), (x, i) -> x > i);
 [2,3]
> SELECT filter(array(0, null, 2, 3, null), x -> x IS NOT NULL);
 [0,2,3]

注意

內部函數可以使用索引數，自 3.0.0 起。

自 2.4.0

find_in_set

find_in_set(str, str_array) - 傳回逗號分隔清單 (str_array) 中指定字串 (str) 的索引 (從 1 開始)。如果找不到字串或指定的字串 (str) 包含逗號，則傳回 0。

範例

> SELECT find_in_set('ab','abc,b,ab,c,def');
 3

自 1.5.0

first

first(expr[, isIgnoreNull]) - 傳回群組列的 expr 第一個值。如果 isIgnoreNull 為 true，則僅傳回非 null 值。

範例

> SELECT first(col) FROM VALUES (10), (5), (20) AS tab(col);
 10
> SELECT first(col) FROM VALUES (NULL), (5), (20) AS tab(col);
 NULL
> SELECT first(col, true) FROM VALUES (NULL), (5), (20) AS tab(col);
 5

注意

此函數是非確定性的，因為其結果取決於列的順序，而列的順序在洗牌後可能是非確定性的。

自 2.0.0

first_value

first_value(expr[, isIgnoreNull]) - 傳回群組列的 expr 第一個值。如果 isIgnoreNull 為 true，則僅傳回非 null 值。

範例

> SELECT first_value(col) FROM VALUES (10), (5), (20) AS tab(col);
 10
> SELECT first_value(col) FROM VALUES (NULL), (5), (20) AS tab(col);
 NULL
> SELECT first_value(col, true) FROM VALUES (NULL), (5), (20) AS tab(col);
 5

注意

此函數是非確定性的，因為其結果取決於列的順序，而列的順序在洗牌後可能是非確定性的。

自 2.0.0

flatten

flatten(arrayOfArrays) - 將陣列的陣列轉換成單一陣列。

範例

> SELECT flatten(array(array(1, 2), array(3, 4)));
 [1,2,3,4]

自 2.4.0

float

float(expr) - 將值 expr 轉換成目標資料類型 float。

自 2.0.1

floor

floor(expr[, scale]) - 傳回向下捨入後最大的數字，且不超過 expr。可以指定選用的 scale 參數來控制捨入行為。

範例

> SELECT floor(-0.1);
 -1
> SELECT floor(5);
 5
> SELECT floor(3.1411, 3);
 3.141
> SELECT floor(3.1411, -3);
 0

自 3.3.0

forall

forall(expr, pred) - 測試謂詞是否對陣列中的所有元素成立。

範例

> SELECT forall(array(1, 2, 3), x -> x % 2 == 0);
 false
> SELECT forall(array(2, 4, 8), x -> x % 2 == 0);
 true
> SELECT forall(array(1, null, 3), x -> x % 2 == 0);
 false
> SELECT forall(array(2, null, 8), x -> x % 2 == 0);
 NULL

自 3.0.0

format_number

format_number(expr1, expr2) - 將數字 expr1 格式化為 '#,###,###.##'，四捨五入到小數點後 expr2 位。如果 expr2 為 0，則結果沒有小數點或小數部分。expr2 也接受使用者指定的格式。這應該像 MySQL 的 FORMAT 一樣運作。

範例

> SELECT format_number(12332.123456, 4);
 12,332.1235
> SELECT format_number(12332.123456, '##################.###');
 12332.123

自 1.5.0

format_string

format_string(strfmt, obj, ...) - 從 printf 風格格式字串傳回格式化字串。

範例

> SELECT format_string("Hello World %d %s", 100, "days");
 Hello World 100 days

自 1.5.0

from_csv

from_csv(csvStr, schema[, options]) - 傳回具有給定 csvStr 和 schema 的結構值。

範例

> SELECT from_csv('1, 0.8', 'a INT, b DOUBLE');
 {"a":1,"b":0.8}
> SELECT from_csv('26/08/2015', 'time Timestamp', map('timestampFormat', 'dd/MM/yyyy'));
 {"time":2015-08-26 00:00:00}

自 3.0.0

from_json

from_json(jsonStr, schema[, options]) - 傳回具有給定 jsonStr 和 schema 的結構值。

範例

> SELECT from_json('{"a":1, "b":0.8}', 'a INT, b DOUBLE');
 {"a":1,"b":0.8}
> SELECT from_json('{"time":"26/08/2015"}', 'time Timestamp', map('timestampFormat', 'dd/MM/yyyy'));
 {"time":2015-08-26 00:00:00}
> SELECT from_json('{"teacher": "Alice", "student": [{"name": "Bob", "rank": 1}, {"name": "Charlie", "rank": 2}]}', 'STRUCT<teacher: STRING, student: ARRAY<STRUCT<name: STRING, rank: INT>>>');
 {"teacher":"Alice","student":[{"name":"Bob","rank":1},{"name":"Charlie","rank":2}]}

自 2.2.0

from_unixtime

from_unixtime(unix_time[, fmt]) - 傳回指定 fmt 中的 unix_time。

引數

unix_time - 要轉換為所提供格式的 UNIX 時間戳記。
fmt - 要遵循的日期/時間格式模式。有關有效的日期和時間格式模式，請參閱日期時間模式。如果省略，則使用 'yyyy-MM-dd HH:mm:ss' 模式。

範例

> SELECT from_unixtime(0, 'yyyy-MM-dd HH:mm:ss');
 1969-12-31 16:00:00

> SELECT from_unixtime(0);
 1969-12-31 16:00:00

自 1.5.0

from_utc_timestamp

from_utc_timestamp(timestamp, timezone) - 給定類似 '2017-07-14 02:40:00.0' 的時間戳記，將其解釋為 UTC 中的時間，並將該時間呈現為給定時區中的時間戳記。例如，'GMT+1' 會產生 '2017-07-14 03:40:00.0'。

範例

> SELECT from_utc_timestamp('2016-08-31', 'Asia/Seoul');
 2016-08-31 09:00:00

自 1.5.0

get

get(array, index) - 傳回給定 (以 0 為基底) index 的陣列元素。如果 index 指向陣列邊界之外，則此函數會傳回 NULL。

範例

> SELECT get(array(1, 2, 3), 0);
 1
> SELECT get(array(1, 2, 3), 3);
 NULL
> SELECT get(array(1, 2, 3), -1);
 NULL

自 3.4.0

get_json_object

get_json_object(json_txt, path) - 從 path 中萃取 JSON 物件。

範例

> SELECT get_json_object('{"a":"b"}', '$.a');
 b

自 1.5.0

getbit

getbit(expr, pos) - 傳回指定位置的位元值 (0 或 1)。位置從右到左編號，從 0 開始。位置引數不能為負值。

範例

> SELECT getbit(11, 0);
 1
> SELECT getbit(11, 2);
 0

自 3.2.0

greatest

greatest(expr, ...) - 傳回所有參數的最大值，略過 NULL 值。

範例

> SELECT greatest(10, 9, 2, 4, 3);
 10

自 1.5.0

grouping

grouping(col) - 指出 GROUP BY 中的指定欄位是否聚合，在結果集中傳回 1 表示聚合或 0 表示未聚合。

範例

> SELECT name, grouping(name), sum(age) FROM VALUES (2, 'Alice'), (5, 'Bob') people(age, name) GROUP BY cube(name);
  Alice 0   2
  Bob   0   5
  NULL  1   7

自 2.0.0

grouping_id

grouping_id([col1[, col2 ..]]) - 傳回群組等級，等於 (grouping(c1) << (n-1)) + (grouping(c2) << (n-2)) + ... + grouping(cn)

範例

> SELECT name, grouping_id(), sum(age), avg(height) FROM VALUES (2, 'Alice', 165), (5, 'Bob', 180) people(age, name, height) GROUP BY cube(name, height);
  Alice 0   2   165.0
  Alice 1   2   165.0
  NULL  3   7   172.5
  Bob   0   5   180.0
  Bob   1   5   180.0
  NULL  2   2   165.0
  NULL  2   5   180.0

注意

輸入欄位應與群組欄位完全相符，或為空 (表示所有群組欄位)。

自 2.0.0

hash

hash(expr1, expr2, ...) - 傳回引數的雜湊值。

範例

> SELECT hash('Spark', array(123), 2);
 -1321691492

自 2.0.0

hex

hex(expr) - 將 expr 轉換為十六進位。

範例

> SELECT hex(17);
 11
> SELECT hex('Spark SQL');
 537061726B2053514C

自 1.5.0

histogram_numeric

histogram_numeric(expr, nb) - 使用 nb 個區間對數值「expr」計算直方圖。回傳值是一個 (x,y) 對陣列，代表直方圖區間的中心。隨著「nb」的值增加，直方圖近似值會更精細，但可能會在異常值周圍產生人工製品。實際上，20-40 個直方圖區間似乎運作良好，而偏態或較小的資料集需要更多區間。請注意，此函式會建立一個區間寬度不均勻的直方圖。它不保證直方圖的均方誤差，但實際上與 R/S-Plus 統計運算套件產生的直方圖相當。注意：回傳值中「x」欄位的輸出類型會從聚合函式中消耗的輸入值傳播。

範例

> SELECT histogram_numeric(col, 5) FROM VALUES (0), (1), (2), (10) AS tab(col);
 [{"x":0,"y":1.0},{"x":1,"y":1.0},{"x":2,"y":1.0},{"x":10,"y":1.0}]

自 3.3.0

hll_sketch_agg

hll_sketch_agg(expr, lgConfigK) - 傳回 HllSketch 可更新的二進位表示。lgConfigK (選用) K 的 log-base-2，其中 K 是 HllSketch 的區塊或槽位數。

範例

> SELECT hll_sketch_estimate(hll_sketch_agg(col, 12)) FROM VALUES (1), (1), (2), (2), (3) tab(col);
 3

自 3.5.0

hll_sketch_estimate

hll_sketch_estimate(expr) - 傳回給定 Datasketches HllSketch 二進位表示的唯一值估計數。

範例

> SELECT hll_sketch_estimate(hll_sketch_agg(col)) FROM VALUES (1), (1), (2), (2), (3) tab(col);
 3

自 3.5.0

hll_union

hll_union(first, second, allowDifferentLgConfigK) - 使用 Datasketches Union 物件合併兩個 Datasketches HllSketch 物件的二進位表示。將 allowDifferentLgConfigK 設為 true 以允許合併具有不同 lgConfigK 值的草圖（預設為 false）。

範例

> SELECT hll_sketch_estimate(hll_union(hll_sketch_agg(col1), hll_sketch_agg(col2))) FROM VALUES (1, 4), (1, 4), (2, 5), (2, 5), (3, 6) tab(col1, col2);
 6

自 3.5.0

hll_union_agg

hll_union_agg(expr, allowDifferentLgConfigK) - 傳回唯一值估計數。allowDifferentLgConfigK (選用) 允許合併具有不同 lgConfigK 值的草圖（預設為 false）。

範例

> SELECT hll_sketch_estimate(hll_union_agg(sketch, true)) FROM (SELECT hll_sketch_agg(col) as sketch FROM VALUES (1) tab(col) UNION ALL SELECT hll_sketch_agg(col, 20) as sketch FROM VALUES (1) tab(col));
 1

自 3.5.0

hour

hour(timestamp) - 傳回字串/時間戳記的小時元件。

範例

> SELECT hour('2009-07-30 12:58:59');
 12

自 1.5.0

hypot

hypot(expr1, expr2) - 傳回 sqrt(expr12 + expr22)。

範例

> SELECT hypot(3, 4);
 5.0

自 1.4.0

if

if(expr1, expr2, expr3) - 如果 expr1 評估為 true，則傳回 expr2；否則傳回 expr3。

範例

> SELECT if(1 < 2, 'a', 'b');
 a

自 1.0.0

ifnull

ifnull(expr1, expr2) - 如果 expr1 為 null，則傳回 expr2；否則傳回 expr1。

範例

> SELECT ifnull(NULL, array('2'));
 ["2"]

自 2.0.0

ilike

str ilike pattern[ ESCAPE escape] - 如果 str 與 pattern 匹配，且 escape 不分大小寫，則傳回 true；如果任何引數為 null，則傳回 null；否則傳回 false。

引數

str - 字串表達式
pattern - 字串表示式。此模式是一個字串，會逐字匹配且不分大小寫，但下列特殊符號除外

_ 在輸入中比對任一字元（類似於 posix 正規表示式中的 .）

% 在輸入中比對 0 個或多個字元（類似於 posix 正規表示式中的 .*）

自 Spark 2.0 起，字串文字在我們的 SQL 解析器中未取消轉義。例如，若要比對「\abc」，樣式應為「\abc」。

當 SQL 設定檔「spark.sql.parser.escapedStringLiterals」已啟用時，它會回溯到 Spark 1.6 關於字串文字解析的行為。例如，如果已啟用設定檔，則比對「\abc」的樣式應為「\\abc」。
escape - 自 Spark 3.0 起新增的字元。預設的 escape 字元為「\」。如果 escape 字元出現在特殊符號或另一個 escape 字元之前，則會比對下一個字元。將任何其他字元進行 escape 是無效的。

範例

> SELECT ilike('Spark', '_Park');
true
> SET spark.sql.parser.escapedStringLiterals=true;
spark.sql.parser.escapedStringLiterals  true
> SELECT '%SystemDrive%\Users\John' ilike '\%SystemDrive\%\\users%';
true
> SET spark.sql.parser.escapedStringLiterals=false;
spark.sql.parser.escapedStringLiterals  false
> SELECT '%SystemDrive%\\USERS\\John' ilike '\%SystemDrive\%\\\\Users%';
true
> SELECT '%SystemDrive%/Users/John' ilike '/%SYSTEMDrive/%//Users%' ESCAPE '/';
true

注意

使用 RLIKE 比對標準正規表示式。

自 3.3.0

in

expr1 in(expr2, expr3, ...) - 如果 expr 等於任何 valN，則傳回 true。

引數

expr1、expr2、expr3 等 - 參數必須為相同類型。

範例

> SELECT 1 in(1, 2, 3);
 true
> SELECT 1 in(2, 3, 4);
 false
> SELECT named_struct('a', 1, 'b', 2) in(named_struct('a', 1, 'b', 1), named_struct('a', 1, 'b', 3));
 false
> SELECT named_struct('a', 1, 'b', 2) in(named_struct('a', 1, 'b', 2), named_struct('a', 1, 'b', 3));
 true

自 1.0.0

initcap

initcap(str) - 傳回 str，其中每個字詞的第一個字母為大寫。所有其他字母為小寫。字詞以空白區隔。

範例

> SELECT initcap('sPark sql');
 Spark Sql

自 1.5.0

inline

inline(expr) - 將結構陣列展開成表格。預設使用欄位名稱 col1、col2 等，除非另有指定。

範例

> SELECT inline(array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b

自 2.0.0

inline_outer

inline_outer(expr) - 將結構陣列展開成表格。預設使用欄位名稱 col1、col2 等，除非另有指定。

範例

> SELECT inline_outer(array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b

自 2.0.0

input_file_block_length

input_file_block_length() - 傳回正在讀取的區塊長度，如果不可用則傳回 -1。

範例

> SELECT input_file_block_length();
 -1

自 2.2.0

input_file_block_start

input_file_block_start() - 傳回正在讀取的區塊的開始偏移量，如果不可用則傳回 -1。

範例

> SELECT input_file_block_start();
 -1

自 2.2.0

input_file_name

input_file_name() - 傳回正在讀取的檔案名稱，如果不可用則傳回空字串。

範例

> SELECT input_file_name();

自 1.5.0

instr

instr(str, substr) - 傳回 substr 在 str 中第一次出現的（以 1 為基底的）索引。

範例

> SELECT instr('SparkSQL', 'SQL');
 6

自 1.5.0

int

int(expr) - 將值 expr 轉換成目標資料類型 int。

自 2.0.1

isnan

isnan(expr) - 如果 expr 為 NaN，則傳回 true，否則傳回 false。

範例

> SELECT isnan(cast('NaN' as double));
 true

自 1.5.0

isnotnull

isnotnull(expr) - 如果 expr 不為 null，則傳回 true，否則傳回 false。

範例

> SELECT isnotnull(1);
 true

自 1.0.0

isnull

isnull(expr) - 如果 expr 為 null，則傳回 true，否則傳回 false。

範例

> SELECT isnull(1);
 false

自 1.0.0

java_method

java_method(class, method[, arg1[, arg2 ..]]) - 使用反射呼叫方法。

範例

> SELECT java_method('java.util.UUID', 'randomUUID');
 c33fb387-8500-4bfa-81d2-6e0e3e930df2
> SELECT java_method('java.util.UUID', 'fromString', 'a5cf6c42-0c85-418f-af6c-3e4e5b1328f2');
 a5cf6c42-0c85-418f-af6c-3e4e5b1328f2

自 2.0.0

json_array_length

json_array_length(jsonArray) - 傳回最外層 JSON 陣列中的元素數量。

引數

jsonArray - JSON 陣列。如果為任何其他有效的 JSON 字串、NULL 或無效的 JSON，則傳回 NULL。

範例

> SELECT json_array_length('[1,2,3,4]');
  4
> SELECT json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]');
  5
> SELECT json_array_length('[1,2');
  NULL

自 3.1.0

json_object_keys

json_object_keys(json_object) - 傳回最外層 JSON 物件的所有金鑰，作為陣列。

引數

json_object - JSON 物件。如果給定有效的 JSON 物件，則最外層物件的所有金鑰將作為陣列傳回。如果為任何其他有效的 JSON 字串、無效的 JSON 字串或空字串，則此函式傳回 null。

範例

> SELECT json_object_keys('{}');
  []
> SELECT json_object_keys('{"key": "value"}');
  ["key"]
> SELECT json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}');
  ["f1","f2"]

自 3.1.0

json_tuple

json_tuple(jsonStr, p1, p2, ..., pn) - 傳回類似函式 get_json_object 的組，但它採用多個名稱。所有輸入參數和輸出欄位類型都是字串。

範例

> SELECT json_tuple('{"a":1, "b":2}', 'a', 'b');
 1  2

自 1.6.0

kurtosis

kurtosis(expr) - 傳回從群組值計算的峰度值。

範例

> SELECT kurtosis(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);
 -0.7014368047529627
> SELECT kurtosis(col) FROM VALUES (1), (10), (100), (10), (1) as tab(col);
 0.19432323191699075

自 1.6.0

lag

lag(input[, offset[, default]]) - 傳回視窗中目前列之前第 offset 列的 input 值。offset 的預設值為 1，而 default 的預設值為 null。如果第 offset 列的 input 值為 null，則傳回 null。如果沒有此類偏移列（例如，當偏移量為 1 時，視窗的第一列沒有任何前一列），則傳回 default。

引數

input - 評估目前列之前 offset 列的字串表達式。
offset - 在分割區中往回跳的列數的 int 表達式。
default - 當偏移列不存在時使用的字串表達式。

範例

> SELECT a, b, lag(b) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   NULL
 A1 1   1
 A1 2   1
 A2 3   NULL

自 2.0.0

last

last(expr[, isIgnoreNull]) - 傳回群組列的 expr 最後一個值。如果 isIgnoreNull 為 true，則只傳回非 null 值

範例

> SELECT last(col) FROM VALUES (10), (5), (20) AS tab(col);
 20
> SELECT last(col) FROM VALUES (10), (5), (NULL) AS tab(col);
 NULL
> SELECT last(col, true) FROM VALUES (10), (5), (NULL) AS tab(col);
 5

注意

此函數是非確定性的，因為其結果取決於列的順序，而列的順序在洗牌後可能是非確定性的。

自 2.0.0

last_day

last_day(date) - 傳回日期所屬月份的最後一天。

範例

> SELECT last_day('2009-01-12');
 2009-01-31

自 1.5.0

last_value

last_value(expr[, isIgnoreNull]) - 傳回群組列的 expr 最後一個值。如果 isIgnoreNull 為 true，則只傳回非 null 值

範例

> SELECT last_value(col) FROM VALUES (10), (5), (20) AS tab(col);
 20
> SELECT last_value(col) FROM VALUES (10), (5), (NULL) AS tab(col);
 NULL
> SELECT last_value(col, true) FROM VALUES (10), (5), (NULL) AS tab(col);
 5

注意

此函數是非確定性的，因為其結果取決於列的順序，而列的順序在洗牌後可能是非確定性的。

自 2.0.0

lcase

lcase(str) - 傳回所有字元都轉換為小寫的 str。

範例

> SELECT lcase('SparkSql');
 sparksql

自 1.0.1

lead

lead(input[, offset[, default]]) - 傳回視窗中目前列之後第 offset 列的 input 值。offset 的預設值為 1，而 default 的預設值為 null。如果第 offset 列的 input 值為 null，則傳回 null。如果沒有此類偏移列（例如，當偏移量為 1 時，視窗的最後一列沒有任何後續列），則傳回 default。

引數

input - 評估目前列之後 offset 列的字串表達式。
offset - 在分割區中向前跳的列數的 int 表達式。
default - 當偏移量大於視窗時使用的字串表達式。預設值為 null。

範例

> SELECT a, b, lead(b) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   2
 A1 2   NULL
 A2 3   NULL

自 2.0.0

least

least(expr, ...) - 傳回所有參數的最小值，略過 null 值。

範例

> SELECT least(10, 9, 2, 4, 3);
 2

自 1.5.0

left

left(str, len) - 從字串 str 傳回最左邊的 len（len 可以是字串類型）個字元，如果 len 小於或等於 0，則結果為空字串。

範例

> SELECT left('Spark SQL', 3);
 Spa
> SELECT left(encode('Spark SQL', 'utf-8'), 3);
 Spa

自 2.3.0

len

len(expr) - 傳回字串資料的字元長度或二進位資料的位元組數。字串資料的長度包含尾隨空白。二進位資料的長度包含二進位零。

範例

> SELECT len('Spark SQL ');
 10
> SELECT len(x'537061726b2053514c');
 9
> SELECT CHAR_LENGTH('Spark SQL ');
 10
> SELECT CHARACTER_LENGTH('Spark SQL ');
 10

自 3.4.0

length

length(expr) - 傳回字串資料的字元長度或二進位資料的位元組數目。字串資料的長度包含尾隨空白。二進位資料的長度包含二進位零。

範例

> SELECT length('Spark SQL ');
 10
> SELECT length(x'537061726b2053514c');
 9
> SELECT CHAR_LENGTH('Spark SQL ');
 10
> SELECT CHARACTER_LENGTH('Spark SQL ');
 10

自 1.5.0

levenshtein

levenshtein(str1, str2[, threshold]) - 傳回兩個給定字串之間的 Levenshtein 距離。如果設定 threshold 且距離大於它，傳回 -1。

範例

> SELECT levenshtein('kitten', 'sitting');
 3
> SELECT levenshtein('kitten', 'sitting', 2);
 -1

自 1.5.0

like

str like pattern[ ESCAPE escape] - 如果 str 符合具有 escape 的 pattern，傳回 true；如果任何引數為 null，傳回 null；否則傳回 false。

引數

str - 字串表達式
pattern - 字串表達式。pattern 是以文字方式比對的字串，但下列特殊符號例外

_ 比對輸入中的任何一個字元（類似於 posix 正規表示法中的 .）\ % 比對輸入中的零個或多個字元（類似於 posix 正規表示法中的 .*）

自 Spark 2.0 起，字串文字在我們的 SQL 解析器中未取消轉義。例如，若要比對「\abc」，樣式應為「\abc」。

當 SQL 設定檔「spark.sql.parser.escapedStringLiterals」已啟用時，它會回溯到 Spark 1.6 關於字串文字解析的行為。例如，如果已啟用設定檔，則比對「\abc」的樣式應為「\\abc」。
escape - 自 Spark 3.0 起新增的字元。預設的 escape 字元為「\」。如果 escape 字元出現在特殊符號或另一個 escape 字元之前，則會比對下一個字元。將任何其他字元進行 escape 是無效的。

範例

> SELECT like('Spark', '_park');
true
> SET spark.sql.parser.escapedStringLiterals=true;
spark.sql.parser.escapedStringLiterals  true
> SELECT '%SystemDrive%\Users\John' like '\%SystemDrive\%\\Users%';
true
> SET spark.sql.parser.escapedStringLiterals=false;
spark.sql.parser.escapedStringLiterals  false
> SELECT '%SystemDrive%\\Users\\John' like '\%SystemDrive\%\\\\Users%';
true
> SELECT '%SystemDrive%/Users/John' like '/%SystemDrive/%//Users%' ESCAPE '/';
true

注意

使用 RLIKE 比對標準正規表示式。

自 1.0.0

ln

ln(expr) - 傳回 expr 的自然對數（以 e 為底）。

範例

> SELECT ln(1);
 0.0

自 1.4.0

localtimestamp

localtimestamp() - 傳回查詢評估開始時沒有時區的目前時間戳記。在同一個查詢中呼叫 localtimestamp 的所有呼叫都會傳回相同的值。

localtimestamp - 傳回查詢評估開始時，以工作階段時區為準的目前當地日期時間。

範例

> SELECT localtimestamp();
 2020-04-25 15:49:11.914

自 3.4.0

locate

locate(substr, str[, pos]) - 傳回 substr 在 str 中第一次出現的位置（在位置 pos 之後）。給定的 pos 和傳回值均以 1 為基準。

範例

> SELECT locate('bar', 'foobarbar');
 4
> SELECT locate('bar', 'foobarbar', 5);
 7
> SELECT POSITION('bar' IN 'foobarbar');
 4

自 1.5.0

log

log(base, expr) - 傳回 expr 的對數，底數為 base。

範例

> SELECT log(10, 100);
 2.0

自 1.5.0

log10

log10(expr) - 傳回 expr 的對數，底數為 10。

範例

> SELECT log10(10);
 1.0

自 1.4.0

log1p

log1p(expr) - 傳回 log(1 + expr)。

範例

> SELECT log1p(0);
 0.0

自 1.4.0

log2

log2(expr) - 傳回 expr 的對數，底數為 2。

範例

> SELECT log2(2);
 1.0

自 1.4.0

lower

lower(str) - 傳回 str，其中所有字元都已轉換為小寫。

範例

> SELECT lower('SparkSql');
 sparksql

自 1.0.1

lpad

lpad(str, len[, pad]) - 傳回 str，左邊以 pad 填補至長度 len。如果 str 比 len 長，傳回值會縮短為 len 個字元或位元組。如果未指定 pad，如果 str 是字元串，則會在左側以空白字元填補；如果是位元組序列，則以零填補。

範例

> SELECT lpad('hi', 5, '??');
 ???hi
> SELECT lpad('hi', 1, '??');
 h
> SELECT lpad('hi', 5);
    hi
> SELECT hex(lpad(unhex('aabb'), 5));
 000000AABB
> SELECT hex(lpad(unhex('aabb'), 5, unhex('1122')));
 112211AABB

自 1.5.0

ltrim

ltrim(str) - 從 str 中移除前導空白字元。

引數

str - 字串表達式
trimStr - 要修剪的修剪字串字元，預設值為單一空白

範例

> SELECT ltrim('    SparkSQL   ');
 SparkSQL

自 1.5.0

luhn_check

luhn_check(str ) - 根據 Luhn 演算法檢查字串中的數字是否有效。這個檢查總和函式廣泛應用於信用卡號碼和政府身分證號碼，用以區分有效的號碼和輸入錯誤的號碼。

範例

> SELECT luhn_check('8112189876');
 true
> SELECT luhn_check('79927398713');
 true
> SELECT luhn_check('79927398714');
 false

自 3.5.0

make_date

make_date(年, 月, 日) - 使用年、月和日欄位建立日期。如果組態 spark.sql.ansi.enabled 為 false，函式會在無效輸入時傳回 NULL。否則，它會擲回錯誤。

引數

年 - 要表示的年，範圍從 1 到 9999
月 - 要表示的月份，範圍從 1 (一月) 到 12 (十二月)
日 - 要表示的日期，範圍從 1 到 31

範例

> SELECT make_date(2013, 7, 15);
 2013-07-15
> SELECT make_date(2019, 7, NULL);
 NULL

自 3.0.0

make_dt_interval

make_dt_interval([天[, 小時[, 分鐘[, 秒]]]]) - 使用天、小時、分鐘和秒建立 DayTimeIntervalType 持續時間。

引數

天 - 天數，可以是正數或負數
小時 - 小時數，可以是正數或負數
分鐘 - 分鐘數，可以是正數或負數
秒 - 秒數，小數部分以微秒精度表示。

範例

> SELECT make_dt_interval(1, 12, 30, 01.001001);
 1 12:30:01.001001000
> SELECT make_dt_interval(2);
 2 00:00:00.000000000
> SELECT make_dt_interval(100, null, 3);
 NULL

自 3.2.0

make_interval

make_interval([年[, 月[, 週[, 天[, 小時[, 分鐘[, 秒]]]]]]]) - 使用年、月、週、天、小時、分鐘和秒建立間隔。

引數

年 - 年數，可以是正數或負數
月 - 月數，可以是正數或負數
週 - 週數，可以是正數或負數
天 - 天數，可以是正數或負數
小時 - 小時數，可以是正數或負數
分鐘 - 分鐘數，可以是正數或負數
秒 - 秒數，小數部分以微秒精度表示。

範例

> SELECT make_interval(100, 11, 1, 1, 12, 30, 01.001001);
 100 years 11 months 8 days 12 hours 30 minutes 1.001001 seconds
> SELECT make_interval(100, null, 3);
 NULL
> SELECT make_interval(0, 1, 0, 1, 0, 0, 100.000001);
 1 months 1 days 1 minutes 40.000001 seconds

自 3.0.0

make_timestamp

make_timestamp(年, 月, 日, 時, 分, 秒[, 時區]) - 使用年、月、日、時、分、秒和時區欄位建立時間戳記。結果資料類型與組態 spark.sql.timestampType 的值一致。如果組態 spark.sql.ansi.enabled 為 false，函式會在無效輸入時傳回 NULL。否則，它會擲回錯誤。

引數

年 - 要表示的年，範圍從 1 到 9999
月 - 要表示的月份，範圍從 1 (一月) 到 12 (十二月)
日 - 要表示的日期，範圍從 1 到 31
時 - 要表示的小時，範圍從 0 到 23
分 - 要表示的分鐘，範圍從 0 到 59
秒 - 要表示的秒數及其微分數，範圍從 0 到 60。該值可以是整數，例如 13，或小數，例如 13.123。如果 sec 引數等於 60，秒數欄位會設為 0，並在最終時間戳記中加上 1 分鐘。
時區 - 時區識別碼。例如，CET、UTC 等。

範例

> SELECT make_timestamp(2014, 12, 28, 6, 30, 45.887);
 2014-12-28 06:30:45.887
> SELECT make_timestamp(2014, 12, 28, 6, 30, 45.887, 'CET');
 2014-12-27 21:30:45.887
> SELECT make_timestamp(2019, 6, 30, 23, 59, 60);
 2019-07-01 00:00:00
> SELECT make_timestamp(2019, 6, 30, 23, 59, 1);
 2019-06-30 23:59:01
> SELECT make_timestamp(null, 7, 22, 15, 30, 0);
 NULL

自 3.0.0

make_timestamp_ltz

make_timestamp_ltz(年, 月, 日, 時, 分, 秒[, 時區]) - 使用年、月、日、時、分、秒和時區欄位建立具有當地時區的目前時間戳記。如果組態 spark.sql.ansi.enabled 為 false，函式會在無效輸入時傳回 NULL。否則，它會擲回錯誤。

引數

年 - 要表示的年，範圍從 1 到 9999
月 - 要表示的月份，範圍從 1 (一月) 到 12 (十二月)
日 - 要表示的日期，範圍從 1 到 31
時 - 要表示的小時，範圍從 0 到 23
分 - 要表示的分鐘，範圍從 0 到 59
秒 - 表示分鐘的秒數及其微分數，範圍從 0 到 60。如果 sec 參數等於 60，則秒數欄位會設為 0，並將 1 分鐘新增至最終時間戳記。
時區 - 時區識別碼。例如，CET、UTC 等。

範例

> SELECT make_timestamp_ltz(2014, 12, 28, 6, 30, 45.887);
 2014-12-28 06:30:45.887
> SELECT make_timestamp_ltz(2014, 12, 28, 6, 30, 45.887, 'CET');
 2014-12-27 21:30:45.887
> SELECT make_timestamp_ltz(2019, 6, 30, 23, 59, 60);
 2019-07-01 00:00:00
> SELECT make_timestamp_ltz(null, 7, 22, 15, 30, 0);
 NULL

自 3.4.0

make_timestamp_ntz

make_timestamp_ntz(年, 月, 日, 時, 分, 秒) - 從年、月、日、時、分、秒欄位建立當地日期時間。如果組態 spark.sql.ansi.enabled 為 false，則函數會在無效輸入時傳回 NULL。否則，它會擲回錯誤。

引數

年 - 要表示的年，範圍從 1 到 9999
月 - 要表示的月份，範圍從 1 (一月) 到 12 (十二月)
日 - 要表示的日期，範圍從 1 到 31
時 - 要表示的小時，範圍從 0 到 23
分 - 要表示的分鐘，範圍從 0 到 59
秒 - 表示分鐘的秒數及其微分數，範圍從 0 到 60。如果 sec 參數等於 60，則秒數欄位會設為 0，並將 1 分鐘新增至最終時間戳記。

範例

> SELECT make_timestamp_ntz(2014, 12, 28, 6, 30, 45.887);
 2014-12-28 06:30:45.887
> SELECT make_timestamp_ntz(2019, 6, 30, 23, 59, 60);
 2019-07-01 00:00:00
> SELECT make_timestamp_ntz(null, 7, 22, 15, 30, 0);
 NULL

自 3.4.0

make_ym_interval

make_ym_interval([年[, 月]]) - 從年、月建立年-月區間。

引數

年 - 年數，可以是正數或負數
月 - 月數，可以是正數或負數

範例

> SELECT make_ym_interval(1, 2);
 1-2
> SELECT make_ym_interval(1, 0);
 1-0
> SELECT make_ym_interval(-1, 1);
 -0-11
> SELECT make_ym_interval(2);
 2-0

自 3.2.0

map

map(key0, value0, key1, value1, ...) - 使用指定的 key/value 對建立地圖。

範例

> SELECT map(1.0, '2', 3.0, '4');
 {1.0:"2",3.0:"4"}

自 2.0.0

map_concat

map_concat(map, ...) - 傳回所有指定地圖的聯集

範例

> SELECT map_concat(map(1, 'a', 2, 'b'), map(3, 'c'));
 {1:"a",2:"b",3:"c"}

自 2.4.0

map_contains_key

map_contains_key(map, key) - 如果地圖包含 key，則傳回 true。

範例

> SELECT map_contains_key(map(1, 'a', 2, 'b'), 1);
 true
> SELECT map_contains_key(map(1, 'a', 2, 'b'), 3);
 false

自 3.3.0

map_entries

map_entries(map) - 傳回指定地圖中所有條目的未排序陣列。

範例

> SELECT map_entries(map(1, 'a', 2, 'b'));
 [{"key":1,"value":"a"},{"key":2,"value":"b"}]

自 3.0.0

map_filter

map_filter(expr, func) - 使用函數篩選地圖中的條目。

範例

> SELECT map_filter(map(1, 0, 2, 2, 3, -1), (k, v) -> k > v);
 {1:0,3:-1}

自 3.0.0

map_from_arrays

map_from_arrays(keys, values) - 使用指定的 key/value 陣列對建立地圖。keys 中的所有元素不應為 null

範例

> SELECT map_from_arrays(array(1.0, 3.0), array('2', '4'));
 {1.0:"2",3.0:"4"}

自 2.4.0

map_from_entries

map_from_entries(arrayOfEntries) - 傳回從指定條目陣列建立的地圖。

範例

> SELECT map_from_entries(array(struct(1, 'a'), struct(2, 'b')));
 {1:"a",2:"b"}

自 2.4.0

map_keys

map_keys(map) - 傳回包含地圖中 key 的未排序陣列。

範例

> SELECT map_keys(map(1, 'a', 2, 'b'));
 [1,2]

自 2.0.0

map_values

map_values(map) - 傳回包含地圖中值的未排序陣列。

範例

> SELECT map_values(map(1, 'a', 2, 'b'));
 ["a","b"]

自 2.0.0

map_zip_with

map_zip_with(map1, map2, function) - 透過將函數套用至具有相同 key 的值對，將兩個指定地圖合併成單一地圖。對於僅出現在其中一個地圖中的 key，NULL 會作為缺少 key 的值傳遞。如果輸入地圖包含重複的 key，則僅會將重複 key 的第一個條目傳遞至 lambda 函數。

範例

> SELECT map_zip_with(map(1, 'a', 2, 'b'), map(1, 'x', 2, 'y'), (k, v1, v2) -> concat(v1, v2));
 {1:"ax",2:"by"}
> SELECT map_zip_with(map('a', 1, 'b', 2), map('b', 3, 'c', 4), (k, v1, v2) -> coalesce(v1, 0) + coalesce(v2, 0));
 {"a":1,"b":5,"c":4}

自 3.0.0

mask

mask(input[, upperChar, lowerChar, digitChar, otherChar]) - 遮蔽指定的字串值。此函數會將字元替換為「X」或「x」，並將數字替換為「n」。這對於建立已移除敏感資訊的表格副本很有用。

引數

input - 要遮蔽的字串值。支援的類型：字串、變動長度字串、字元
upperChar - 要用來替換大寫字元的字元。指定 NULL 以保留原始字元。預設值：『X』
lowerChar - 要用來替換小寫字元的字元。指定 NULL 以保留原始字元。預設值：『x』
digitChar - 要用來替換數字字元的字元。指定 NULL 以保留原始字元。預設值：『n』
otherChar - 要用來替換所有其他字元的字元。指定 NULL 以保留原始字元。預設值：NULL

範例

> SELECT mask('abcd-EFGH-8765-4321');
  xxxx-XXXX-nnnn-nnnn
> SELECT mask('abcd-EFGH-8765-4321', 'Q');
  xxxx-QQQQ-nnnn-nnnn
> SELECT mask('AbCD123-@$#', 'Q', 'q');
  QqQQnnn-@$#
> SELECT mask('AbCD123-@$#');
  XxXXnnn-@$#
> SELECT mask('AbCD123-@$#', 'Q');
  QxQQnnn-@$#
> SELECT mask('AbCD123-@$#', 'Q', 'q');
  QqQQnnn-@$#
> SELECT mask('AbCD123-@$#', 'Q', 'q', 'd');
  QqQQddd-@$#
> SELECT mask('AbCD123-@$#', 'Q', 'q', 'd', 'o');
  QqQQdddoooo
> SELECT mask('AbCD123-@$#', NULL, 'q', 'd', 'o');
  AqCDdddoooo
> SELECT mask('AbCD123-@$#', NULL, NULL, 'd', 'o');
  AbCDdddoooo
> SELECT mask('AbCD123-@$#', NULL, NULL, NULL, 'o');
  AbCD123oooo
> SELECT mask(NULL, NULL, NULL, NULL, 'o');
  NULL
> SELECT mask(NULL);
  NULL
> SELECT mask('AbCD123-@$#', NULL, NULL, NULL, NULL);
  AbCD123-@$#

自 3.4.0

max

max(expr) - 傳回 expr 的最大值。

範例

> SELECT max(col) FROM VALUES (10), (50), (20) AS tab(col);
 50

自 1.0.0

max_by

max_by(x, y) - 傳回與 y 最大值關聯的 x 值。

範例

> SELECT max_by(x, y) FROM VALUES ('a', 10), ('b', 50), ('c', 20) AS tab(x, y);
 b

自 3.0.0

md5

md5(expr) - 傳回 expr 的 MD5 128 位元組檢查碼，為十六進位字串。

範例

> SELECT md5('Spark');
 8cde774d6f7333752ed72cacddb05126

自 1.5.0

mean

mean(expr) - 傳回從群組值計算的平均值。

範例

> SELECT mean(col) FROM VALUES (1), (2), (3) AS tab(col);
 2.0
> SELECT mean(col) FROM VALUES (1), (2), (NULL) AS tab(col);
 1.5

自 1.0.0

median

median(col) - 傳回數值或 ANSI 區間欄位 col 的中位數。

範例

> SELECT median(col) FROM VALUES (0), (10) AS tab(col);
 5.0
> SELECT median(col) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-5

自 3.4.0

min

min(expr) - 傳回 expr 的最小值。

範例

> SELECT min(col) FROM VALUES (10), (-1), (20) AS tab(col);
 -1

自 1.0.0

min_by

min_by(x, y) - 傳回與 y 最小值關聯的 x 值。

範例

> SELECT min_by(x, y) FROM VALUES ('a', 10), ('b', 50), ('c', 20) AS tab(x, y);
 a

自 3.0.0

minute

minute(timestamp) - 傳回字串/時間戳記的分鐘組成部分。

範例

> SELECT minute('2009-07-30 12:58:59');
 58

自 1.5.0

mod

expr1 mod expr2 - 傳回 expr1/expr2 後的餘數。

範例

> SELECT 2 % 1.8;
 0.2
> SELECT MOD(2, 1.8);
 0.2

自 1.0.0

mode

mode(col) - 傳回 col 內值的最常出現值。NULL 值會被忽略。如果所有值都是 NULL，或有 0 列，傳回 NULL。

範例

> SELECT mode(col) FROM VALUES (0), (10), (10) AS tab(col);
 10
> SELECT mode(col) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '10' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-10
> SELECT mode(col) FROM VALUES (0), (10), (10), (null), (null), (null) AS tab(col);
 10

自 3.4.0

monotonically_increasing_id

monotonically_increasing_id() - 傳回單調遞增的 64 位元組整數。保證產生的 ID 單調遞增且唯一，但不是連續的。目前的實作將分割 ID 放入高 31 位元組，而低 33 位元組代表每個分割內的記錄編號。假設資料框有少於 10 億個分割，且每個分割有少於 80 億筆記錄。此函式是非確定性的，因為其結果取決於分割 ID。

範例

> SELECT monotonically_increasing_id();
 0

自 1.4.0

month

month(date) - 傳回日期/時間戳記的月份組成部分。

範例

> SELECT month('2016-07-30');
 7

自 1.5.0

months_between

months_between(timestamp1, timestamp2[, roundOff]) - 如果 timestamp1 晚於 timestamp2，則結果為正數。如果 timestamp1 和 timestamp2 在同一天，或兩者都是該月的最後一天，則會忽略時間。否則，差異會根據每個月 31 天計算，並四捨五入到 8 位數，除非 roundOff=false。

範例

> SELECT months_between('1997-02-28 10:30:00', '1996-10-30');
 3.94959677
> SELECT months_between('1997-02-28 10:30:00', '1996-10-30', false);
 3.9495967741935485

自 1.5.0

named_struct

named_struct(name1, val1, name2, val2, ...) - 使用給定的欄位名稱和值建立結構。

範例

> SELECT named_struct("a", 1, "b", 2, "c", 3);
 {"a":1,"b":2,"c":3}

自 1.5.0

nanvl

nanvl(expr1, expr2) - 如果 expr1 不是 NaN，則傳回 expr1，否則傳回 expr2。

範例

> SELECT nanvl(cast('NaN' as double), 123);
 123.0

自 1.5.0

negative

negative(expr) - 傳回 expr 的否定值。

範例

> SELECT negative(1);
 -1

自 1.0.0

next_day

next_day(start_date, day_of_week) - 傳回晚於 start_date 且名稱如指示的第一個日期。如果至少一個輸入參數為 NULL，則此函式會傳回 NULL。當兩個輸入參數都不為 NULL，且 day_of_week 是無效輸入時，如果 spark.sql.ansi.enabled 設為 true，此函式會擲出 IllegalArgumentException，否則傳回 NULL。

範例

> SELECT next_day('2015-01-14', 'TU');
 2015-01-20

自 1.5.0

not

not expr - 邏輯非。

範例

> SELECT not true;
 false
> SELECT not false;
 true
> SELECT not NULL;
 NULL

自 1.0.0

now

now() - 傳回查詢評估開始時的目前時間戳記。

範例

> SELECT now();
 2020-04-25 15:49:11.914

自 1.6.0

nth_value

nth_value(input[, offset]) - 傳回視窗框架中從開始處第 offset 列的 input 值。偏移量從 1 開始。如果 ignoreNulls=true，我們會在尋找第 offset 列時略過 Null。否則，每一列都會計入 offset。如果沒有這樣的第 offset 列（例如，當偏移量為 10，視窗框架大小小於 10），則傳回 Null。

引數

input - 函數運算的目標欄或運算式。
offset - 正整數文字，用來表示視窗框架中的偏移量。從 1 開始。
ignoreNulls - 選擇性規格，表示 NthValue 應在決定要使用哪一列時略過 Null 值。

範例

> SELECT a, b, nth_value(b, 2) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   1
 A1 2   1
 A2 3   NULL

自 3.1.0

ntile

ntile(n) - 將每個視窗分割區的列分成從 1 到最多 n 的 n 個區段。

引數

buckets - 整數運算式，表示要將列分成多少個區段。預設值為 1。

範例

> SELECT a, b, ntile(2) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   1
 A1 2   2
 A2 3   1

自 2.0.0

nullif

nullif(expr1, expr2) - 如果 expr1 等於 expr2，則傳回 Null，否則傳回 expr1。

範例

> SELECT nullif(2, 2);
 NULL

自 2.0.0

nvl

nvl(expr1, expr2) - 如果 expr1 為 Null，則傳回 expr2，否則傳回 expr1。

範例

> SELECT nvl(NULL, array('2'));
 ["2"]

自 2.0.0

nvl2

nvl2(expr1, expr2, expr3) - 如果 expr1 不為 Null，則傳回 expr2，否則傳回 expr3。

範例

> SELECT nvl2(NULL, 2, 1);
 1

自 2.0.0

octet_length

octet_length(expr) - 傳回字串資料的位元組長度或二進位資料的位元組數。

範例

> SELECT octet_length('Spark SQL');
 9
> SELECT octet_length(x'537061726b2053514c');
 9

自 2.3.0

or

expr1 or expr2 - 邏輯 OR。

範例

> SELECT true or false;
 true
> SELECT false or false;
 false
> SELECT true or NULL;
 true
> SELECT false or NULL;
 NULL

自 1.0.0

overlay

overlay(input, replace, pos[, len]) - 以從 pos 開始且長度為 len 的 replace 取代 input。

範例

> SELECT overlay('Spark SQL' PLACING '_' FROM 6);
 Spark_SQL
> SELECT overlay('Spark SQL' PLACING 'CORE' FROM 7);
 Spark CORE
> SELECT overlay('Spark SQL' PLACING 'ANSI ' FROM 7 FOR 0);
 Spark ANSI SQL
> SELECT overlay('Spark SQL' PLACING 'tructured' FROM 2 FOR 4);
 Structured SQL
> SELECT overlay(encode('Spark SQL', 'utf-8') PLACING encode('_', 'utf-8') FROM 6);
 Spark_SQL
> SELECT overlay(encode('Spark SQL', 'utf-8') PLACING encode('CORE', 'utf-8') FROM 7);
 Spark CORE
> SELECT overlay(encode('Spark SQL', 'utf-8') PLACING encode('ANSI ', 'utf-8') FROM 7 FOR 0);
 Spark ANSI SQL
> SELECT overlay(encode('Spark SQL', 'utf-8') PLACING encode('tructured', 'utf-8') FROM 2 FOR 4);
 Structured SQL

自 3.0.0

parse_url

parse_url(url, partToExtract[, key]) - 從 URL 中萃取部分。

範例

> SELECT parse_url('https://spark.dev.org.tw/path?query=1', 'HOST');
 spark.apache.org
> SELECT parse_url('https://spark.dev.org.tw/path?query=1', 'QUERY');
 query=1
> SELECT parse_url('https://spark.dev.org.tw/path?query=1', 'QUERY', 'query');
 1

自 2.0.0

percent_rank

percent_rank() - 計算一組值中某個值的百分比排名。

引數

children - 用於作為排名基礎；children 中的一個值變更會觸發排名變更。這是一個內部參數，由分析器指定。

範例

> SELECT a, b, percent_rank(b) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   0.0
 A1 1   0.0
 A1 2   1.0
 A2 3   0.0

自 2.0.0

percentile

percentile(col, percentage [, frequency]) - 傳回數值或 ANSI 間隔欄 col 在給定百分比下的精確百分比值。percentage 的值必須介於 0.0 和 1.0 之間。frequency 的值應為正整數

percentile(col, array(percentage1 [, percentage2]...) [, frequency]) - 傳回數值欄 col 在給定百分比下的精確百分比值陣列。百分比陣列的每個值都必須介於 0.0 和 1.0 之間。frequency 的值應為正整數

範例

> SELECT percentile(col, 0.3) FROM VALUES (0), (10) AS tab(col);
 3.0
> SELECT percentile(col, array(0.25, 0.75)) FROM VALUES (0), (10) AS tab(col);
 [2.5,7.5]
> SELECT percentile(col, 0.5) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-5
> SELECT percentile(col, array(0.2, 0.5)) FROM VALUES (INTERVAL '0' SECOND), (INTERVAL '10' SECOND) AS tab(col);
 [0 00:00:02.000000000,0 00:00:05.000000000]

自 2.1.0

percentile_approx

percentile_approx(col, percentage [, accuracy]) - 傳回數值或 ansi 間隔欄 col 的近似 percentile，它是已排序 col 值（從最小到最大排序）中最小的值，且不超過 percentage 的 col 值小於或等於該值。percentage 的值必須介於 0.0 和 1.0 之間。accuracy 參數（預設值：10000）是正數文字，用於控制近似精確度，代價是記憶體。accuracy 的值越高，精確度越好，1.0/accuracy 是近似的相對誤差。當 percentage 是陣列時，百分比陣列的每個值都必須介於 0.0 和 1.0 之間。在此情況下，傳回欄 col 在給定百分比陣列下的近似百分比陣列。

範例

> SELECT percentile_approx(col, array(0.5, 0.4, 0.1), 100) FROM VALUES (0), (1), (2), (10) AS tab(col);
 [1,1,0]
> SELECT percentile_approx(col, 0.5, 100) FROM VALUES (0), (6), (7), (9), (10) AS tab(col);
 7
> SELECT percentile_approx(col, 0.5, 100) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '1' MONTH), (INTERVAL '2' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-1
> SELECT percentile_approx(col, array(0.5, 0.7), 100) FROM VALUES (INTERVAL '0' SECOND), (INTERVAL '1' SECOND), (INTERVAL '2' SECOND), (INTERVAL '10' SECOND) AS tab(col);
 [0 00:00:01.000000000,0 00:00:02.000000000]

自 2.1.0

pi

pi() - 傳回 pi。

範例

> SELECT pi();
 3.141592653589793

自 1.5.0

pmod

pmod(expr1, expr2) - 傳回 expr1 對 expr2 取模的正值。

範例

> SELECT pmod(10, 3);
 1
> SELECT pmod(-10, 3);
 2

自 1.5.0

posexplode

posexplode(expr) - 將陣列 expr 的元素分隔成多列，並加上位置，或將映射 expr 的元素分隔成多列和多欄，並加上位置。除非另有指定，否則會使用欄位名稱 pos 表示位置，使用 col 表示陣列的元素，或使用 key 和 value 表示映射的元素。

範例

> SELECT posexplode(array(10,20));
 0  10
 1  20
> SELECT * FROM posexplode(array(10,20));
 0  10
 1  20

自 2.0.0

posexplode_outer

posexplode_outer(expr) - 將陣列 expr 的元素分隔成多列，並加上位置，或將映射 expr 的元素分隔成多列和多欄，並加上位置。除非另有指定，否則會使用欄位名稱 pos 表示位置，使用 col 表示陣列的元素，或使用 key 和 value 表示映射的元素。

範例

> SELECT posexplode_outer(array(10,20));
 0  10
 1  20
> SELECT * FROM posexplode_outer(array(10,20));
 0  10
 1  20

自 2.0.0

position

position(substr, str[, pos]) - 傳回 substr 在 str 中第一次出現的位置，位置從 pos 開始。指定的 pos 和傳回值都是從 1 開始算起。

範例

> SELECT position('bar', 'foobarbar');
 4
> SELECT position('bar', 'foobarbar', 5);
 7
> SELECT POSITION('bar' IN 'foobarbar');
 4

自 1.5.0

positive

positive(expr) - 傳回 expr 的值。

範例

> SELECT positive(1);
 1

自 1.5.0

pow

pow(expr1, expr2) - 將 expr1 乘到 expr2 次方。

範例

> SELECT pow(2, 3);
 8.0

自 1.4.0

power

power(expr1, expr2) - 將 expr1 乘到 expr2 次方。

範例

> SELECT power(2, 3);
 8.0

自 1.4.0

printf

printf(strfmt, obj, ...) - 從 printf 格式字串傳回一個格式化字串。

範例

> SELECT printf("Hello World %d %s", 100, "days");
 Hello World 100 days

自 1.5.0

quarter

quarter(date) - 傳回日期所在的年份的第幾季，範圍為 1 到 4。

範例

> SELECT quarter('2016-08-31');
 3

自 1.5.0

radians

radians(expr) - 將角度轉換成弧度。

引數

expr - 以角度為單位的角度

範例

> SELECT radians(180);
 3.141592653589793

自 1.4.0

raise_error

raise_error(expr) - 擲回一個包含 expr 的例外狀況。

範例

> SELECT raise_error('custom error message');
 java.lang.RuntimeException
 custom error message

自 3.1.0

rand

rand([seed]) - 傳回一個隨機值，其獨立同分布 (i.i.d.) 均勻分布在 [0, 1) 中。

範例

> SELECT rand();
 0.9629742951434543
> SELECT rand(0);
 0.7604953758285915
> SELECT rand(null);
 0.7604953758285915

注意

此函數在一般情況下是非確定性的。

自 1.5.0

randn

randn([seed]) - 傳回一個隨機值，其獨立同分布 (i.i.d.) 從標準常態分布中抽取。

範例

> SELECT randn();
 -0.3254147983080288
> SELECT randn(0);
 1.6034991609278433
> SELECT randn(null);
 1.6034991609278433

注意

此函數在一般情況下是非確定性的。

自 1.5.0

random

random([seed]) - 傳回一個隨機值，其獨立同分布 (i.i.d.) 均勻分布在 [0, 1) 中。

範例

> SELECT random();
 0.9629742951434543
> SELECT random(0);
 0.7604953758285915
> SELECT random(null);
 0.7604953758285915

注意

此函數在一般情況下是非確定性的。

自 1.5.0

rank

rank() - 計算一組值中某個值的排名。結果為 partition 排序中，小於或等於目前列的列數加一。這些值會在順序中產生間隔。

引數

children - 用於作為排名基礎；children 中的一個值變更會觸發排名變更。這是一個內部參數，由分析器指定。

範例

> SELECT a, b, rank(b) OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   1
 A1 2   3
 A2 3   1

自 2.0.0

reduce

reduce(expr, start, merge, finish) - 將二元運算子套用至初始狀態和陣列中的所有元素，並將其簡化為單一狀態。最終狀態會透過套用完成函數轉換為最終結果。

範例

> SELECT reduce(array(1, 2, 3), 0, (acc, x) -> acc + x);
 6
> SELECT reduce(array(1, 2, 3), 0, (acc, x) -> acc + x, acc -> acc * 10);
 60

自 3.4.0

reflect

reflect(class, method[, arg1[, arg2 ..]]) - 使用反射呼叫方法。

範例

> SELECT reflect('java.util.UUID', 'randomUUID');
 c33fb387-8500-4bfa-81d2-6e0e3e930df2
> SELECT reflect('java.util.UUID', 'fromString', 'a5cf6c42-0c85-418f-af6c-3e4e5b1328f2');
 a5cf6c42-0c85-418f-af6c-3e4e5b1328f2

自 2.0.0

regexp

regexp(str, regexp) - 如果 str 與 regexp 相符，則傳回 true，否則傳回 false。

引數

str - 字串表達式
regexp - 字串表達式。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。

範例

> SET spark.sql.parser.escapedStringLiterals=true;
spark.sql.parser.escapedStringLiterals  true
> SELECT regexp('%SystemDrive%\Users\John', '%SystemDrive%\\Users.*');
true
> SET spark.sql.parser.escapedStringLiterals=false;
spark.sql.parser.escapedStringLiterals  false
> SELECT regexp('%SystemDrive%\\Users\\John', '%SystemDrive%\\\\Users.*');
true

注意

使用 LIKE 來符合簡單的字串模式。

自 3.2.0

regexp_count

regexp_count(str, regexp) - 傳回正規表示式模式 regexp 在字串 str 中符合的次數。

引數

str - 字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

範例

> SELECT regexp_count('Steven Jones and Stephen Smith are the best players', 'Ste(v|ph)en');
 2
> SELECT regexp_count('abcdefghijklmnopqrstuvwxyz', '[a-z]{3}');
 8

自 3.4.0

regexp_extract

regexp_extract(str, regexp[, idx]) - 從 str 中擷取第一個符合 regexp 表達式且對應於正規表示式群組索引的字串。

引數

str - 字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。
idx - 代表群組索引的整數表達式。正規表示式可能包含多個群組。idx 指出要擷取哪個正規表示式群組。群組索引應為非負值。idx 的最小值為 0，表示符合整個正規表示式。如果未指定 idx，預設群組索引值為 1。idx 參數是 Java 正規表示式 Matcher group() 方法索引。

範例

> SELECT regexp_extract('100-200', '(\\d+)-(\\d+)', 1);
 100

自 1.5.0

regexp_extract_all

regexp_extract_all(str, regexp[, idx]) - 從 str 中擷取所有符合 regexp 表達式且對應於正規表示式群組索引的字串。

引數

str - 字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。
idx - 表示群組索引的整數表達式。正規表示法可能包含多個群組。idx 表示要提取的正規表示法群組。群組索引應為非負數。idx 的最小值為 0，表示比對整個正規表示法。如果未指定 idx，預設群組索引值為 1。idx 參數是 Java 正規表示法 Matcher group() 方法索引。

範例

> SELECT regexp_extract_all('100-200, 300-400', '(\\d+)-(\\d+)', 1);
 ["100","300"]

自 3.1.0

regexp_instr

regexp_instr(str, regexp) - 在字串中搜尋正規表示法，並傳回一個整數，表示匹配子字串的起始位置。位置從 1 開始，而非 0。如果找不到匹配，傳回 0。

引數

str - 字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。

範例

> SELECT regexp_instr('user@spark.apache.org', '@[^.]*');
 5

自 3.4.0

regexp_like

regexp_like(str, regexp) - 如果 str 匹配 regexp，傳回 true，否則傳回 false。

引數

str - 字串表達式
regexp - 字串表達式。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。

範例

> SET spark.sql.parser.escapedStringLiterals=true;
spark.sql.parser.escapedStringLiterals  true
> SELECT regexp_like('%SystemDrive%\Users\John', '%SystemDrive%\\Users.*');
true
> SET spark.sql.parser.escapedStringLiterals=false;
spark.sql.parser.escapedStringLiterals  false
> SELECT regexp_like('%SystemDrive%\\Users\\John', '%SystemDrive%\\\\Users.*');
true

注意

使用 LIKE 來符合簡單的字串模式。

自 3.2.0

regexp_replace

regexp_replace(str, regexp, rep[, position]) - 使用 rep 取代 str 中所有匹配 regexp 的子字串。

引數

str - 要搜尋正規表示法模式匹配的字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。
rep - 要取代匹配子字串的字串表達式。
position - 表示在 str 中開始搜尋的位置的正整數文字。預設值為 1。如果位置大於 str 中的字元數，結果為 str。

範例

> SELECT regexp_replace('100-200', '(\\d+)', 'num');
 num-num

自 1.5.0

regexp_substr

regexp_substr(str, regexp) - 傳回在字串 str 中匹配正規表示法 regexp 的子字串。如果找不到正規表示法，結果為 null。

引數

str - 字串表達式。
regexp - 代表正規表示式的字串。正規表示式字串應為 Java 正規表示式。

範例

> SELECT regexp_substr('Steven Jones and Stephen Smith are the best players', 'Ste(v|ph)en');
 Steven
> SELECT regexp_substr('Steven Jones and Stephen Smith are the best players', 'Jeck');
 NULL

自 3.4.0

regr_avgx

regr_avgx(y, x) - 傳回群組中非空值對應應變數的平均值，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_avgx(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 2.75
> SELECT regr_avgx(y, x) FROM VALUES (1, null) AS tab(y, x);
 NULL
> SELECT regr_avgx(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> SELECT regr_avgx(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 3.0
> SELECT regr_avgx(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 3.0

自 3.3.0

regr_avgy

regr_avgy(y, x) - 傳回群組中非空值對應自變數的平均值，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_avgy(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 1.75
> SELECT regr_avgy(y, x) FROM VALUES (1, null) AS tab(y, x);
 NULL
> SELECT regr_avgy(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> SELECT regr_avgy(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 1.6666666666666667
> SELECT regr_avgy(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 1.5

自 3.3.0

regr_count

regr_count(y, x) - 傳回群組中非空值數字對應的數量，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_count(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 4
> SELECT regr_count(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 3
> SELECT regr_count(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 2

自 3.3.0

regr_intercept

regr_intercept(y, x) - 傳回群組中非空值對應單變數線性回歸線的截距，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_intercept(y, x) FROM VALUES (1,1), (2,2), (3,3) AS tab(y, x);
 0.0
> SELECT regr_intercept(y, x) FROM VALUES (1, null) AS tab(y, x);
 NULL
> SELECT regr_intercept(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL

自 3.4.0

regr_r2

regr_r2(y, x) - 傳回群組中非空值對應的決定係數，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_r2(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 0.2727272727272727
> SELECT regr_r2(y, x) FROM VALUES (1, null) AS tab(y, x);
 NULL
> SELECT regr_r2(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> SELECT regr_r2(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 0.7500000000000001
> SELECT regr_r2(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 1.0

自 3.3.0

regr_slope

regr_slope(y, x) - 傳回群組中非空值對應線性回歸線的斜率，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_slope(y, x) FROM VALUES (1,1), (2,2), (3,3) AS tab(y, x);
 1.0
> SELECT regr_slope(y, x) FROM VALUES (1, null) AS tab(y, x);
 NULL
> SELECT regr_slope(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL

自 3.4.0

regr_sxx

regr_sxx(y, x) - 傳回群組中非空值對應的 REGR_COUNT(y, x) * VAR_POP(x)，其中 y 是應變數，x 是自變數。

範例

> SELECT regr_sxx(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 2.75
> SELECT regr_sxx(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 2.0
> SELECT regr_sxx(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 2.0

自 3.4.0

regr_sxy

regr_sxy(y, x) - 傳回群組中非空值對的 REGR_COUNT(y, x) * COVAR_POP(y, x)，其中 y 為依變數，x 為自變數。

範例

> SELECT regr_sxy(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 0.75
> SELECT regr_sxy(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 1.0
> SELECT regr_sxy(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 1.0

自 3.4.0

regr_syy

regr_syy(y, x) - 傳回群組中非空值對的 REGR_COUNT(y, x) * VAR_POP(y)，其中 y 為依變數，x 為自變數。

範例

> SELECT regr_syy(y, x) FROM VALUES (1, 2), (2, 2), (2, 3), (2, 4) AS tab(y, x);
 0.75
> SELECT regr_syy(y, x) FROM VALUES (1, 2), (2, null), (2, 3), (2, 4) AS tab(y, x);
 0.6666666666666666
> SELECT regr_syy(y, x) FROM VALUES (1, 2), (2, null), (null, 3), (2, 4) AS tab(y, x);
 0.5

自 3.4.0

repeat

repeat(str, n) - 傳回重複給定字串值 n 次的字串。

範例

> SELECT repeat('123', 2);
 123123

自 1.5.0

replace

replace(str, search[, replace]) - 以 replace 取代 search 的所有出現。

引數

str - 字串表達式
search - 字串表達式。如果在 str 中找不到 search，str 會不變傳回。
replace - 字串表達式。如果未指定 replace 或為空字串，則不會取代從 str 中移除的字串。

範例

> SELECT replace('ABCabc', 'abc', 'DEF');
 ABCDEF

自 2.3.0

reverse

reverse(array) - 傳回反轉的字串或元素順序反轉的陣列。

範例

> SELECT reverse('Spark SQL');
 LQS krapS
> SELECT reverse(array(2, 1, 4, 3));
 [3,4,1,2]

注意

自 2.4.0 起提供陣列的反向邏輯。

自 1.5.0

right

right(str, len) - 傳回字串 str 中最右邊的 len(len 可以是字串類型) 個字元，如果 len 小於或等於 0，結果為空字串。

範例

> SELECT right('Spark SQL', 3);
 SQL

自 2.3.0

rint

rint(expr) - 傳回與引數值最接近且等於數學整數的雙精度值。

範例

> SELECT rint(12.3456);
 12.0

自 1.4.0

rlike

rlike(str, regexp) - 如果 str 符合 regexp，傳回 true，否則傳回 false。

引數

str - 字串表達式
regexp - 字串表達式。正規表示式字串應為 Java 正規表示式。

自 Spark 2.0 起，SQL 解析器會取消字串文字（包括正規表示式模式）的跳脫。例如，若要符合「\abc」，regexp 的正規表示式可以是「^\abc$」。

有一個 SQL 設定「spark.sql.parser.escapedStringLiterals」，可使用它來回歸到 Spark 1.6 關於字串文字剖析的行為。例如，如果啟用設定，可以符合「\abc」的 regexp 為「^\abc$」。

範例

> SET spark.sql.parser.escapedStringLiterals=true;
spark.sql.parser.escapedStringLiterals  true
> SELECT rlike('%SystemDrive%\Users\John', '%SystemDrive%\\Users.*');
true
> SET spark.sql.parser.escapedStringLiterals=false;
spark.sql.parser.escapedStringLiterals  false
> SELECT rlike('%SystemDrive%\\Users\\John', '%SystemDrive%\\\\Users.*');
true

注意

使用 LIKE 來符合簡單的字串模式。

自 1.0.0

round

round(expr, d) - 使用 HALF_UP 捨入模式將 expr 捨入到小數點後 d 位。

範例

> SELECT round(2.5, 0);
 3

自 1.5.0

row_number

row_number() - 根據視窗分割區中列的順序，為每一列指定一個唯一的順序數字，從 1 開始。

範例

> SELECT a, b, row_number() OVER (PARTITION BY a ORDER BY b) FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) tab(a, b);
 A1 1   1
 A1 1   2
 A1 2   3
 A2 3   1

自 2.0.0

rpad

rpad(str, len[, pad]) - 傳回 str，右邊以 pad 填補至長度 len。如果 str 長度大於 len，傳回值會縮短為 len 個字元。如果未指定 pad，如果 str 是字元字串，則會以空白字元在右側填補 str，如果是二進位字串，則會以零填補。

範例

> SELECT rpad('hi', 5, '??');
 hi???
> SELECT rpad('hi', 1, '??');
 h
> SELECT rpad('hi', 5);
 hi
> SELECT hex(rpad(unhex('aabb'), 5));
 AABB000000
> SELECT hex(rpad(unhex('aabb'), 5, unhex('1122')));
 AABB112211

自 1.5.0

rtrim

rtrim(str) - 移掉 str 中尾端的空白字元。

引數

str - 字串表達式
trimStr - 要修剪的修剪字串字元，預設值為單一空白

範例

> SELECT rtrim('    SparkSQL   ');
 SparkSQL

自 1.5.0

schema_of_csv

schema_of_csv(csv[, options]) - 傳回 CSV 字串的 DDL 格式中的結構。

範例

> SELECT schema_of_csv('1,abc');
 STRUCT<_c0: INT, _c1: STRING>

自 3.0.0

schema_of_json

schema_of_json(json[, options]) - 傳回 JSON 字串的 DDL 格式中的結構。

範例

> SELECT schema_of_json('[{"col":0}]');
 ARRAY<STRUCT<col: BIGINT>>
> SELECT schema_of_json('[{"col":01}]', map('allowNumericLeadingZeros', 'true'));
 ARRAY<STRUCT<col: BIGINT>>

自 2.4.0

sec

sec(expr) - 傳回 expr 的割線，如同 1/java.lang.Math.cos 計算的結果。

引數

expr - 以弧度為單位的角度

範例

> SELECT sec(0);
 1.0

自 3.3.0

second

second(timestamp) - 傳回字串/時間戳記的秒鐘元件。

範例

> SELECT second('2009-07-30 12:58:59');
 59

自 1.5.0

sentences

sentences(str[, lang, country]) - 將 str 分割成陣列的陣列的字詞。

範例

> SELECT sentences('Hi there! Good morning.');
 [["Hi","there"],["Good","morning"]]

自 2.0.0

sequence

sequence(start, stop, step) - 從 start 到 stop (包含) 產生一個陣列的元素，以 step 為增量。傳回元素的類型與引數表達式的類型相同。

支援的類型有：位元組、短整數、整數、長整數、日期、時間戳記。

開始和停止表達式必須解析為相同的類型。如果開始和停止表達式解析為「日期」或「時間戳記」類型，則步驟表達式必須解析為「間隔」或「年-月間隔」或「日-時間間隔」類型，否則解析為與開始和停止表達式相同的類型。

引數

開始 - 表達式。範圍的開始。
停止 - 表達式。範圍的結束（包含）。
步驟 - 選擇性表達式。範圍的步驟。如果開始小於或等於停止，則步驟預設為 1，否則為 -1。對於時間序列，分別為 1 天和 -1 天。如果開始大於停止，則步驟必須為負數，反之亦然。

範例

> SELECT sequence(1, 5);
 [1,2,3,4,5]
> SELECT sequence(5, 1);
 [5,4,3,2,1]
> SELECT sequence(to_date('2018-01-01'), to_date('2018-03-01'), interval 1 month);
 [2018-01-01,2018-02-01,2018-03-01]
> SELECT sequence(to_date('2018-01-01'), to_date('2018-03-01'), interval '0-1' year to month);
 [2018-01-01,2018-02-01,2018-03-01]

自 2.4.0

session_window

session_window(time_column, gap_duration) - 產生會話視窗，給定指定欄位和間隔持續時間的時間戳記。請參閱結構化串流指南文件中的「時間視窗類型」以取得詳細說明和範例：https://spark.dev.org.tw/docs/latest/structured-streaming-programming-guide.html#types-of-time-windows

引數

time_column - 欄位或表達式，用作依時間視窗化的時間戳記。時間欄位必須為 TimestampType。
gap_duration - 字串，指定會話逾時，表示為「間隔值」（請參閱間隔文字以取得更多詳細資料），用於固定間隔持續時間，或針對每個輸入套用的表達式，並評估為動態間隔持續時間的「間隔值」。

範例

> SELECT a, session_window.start, session_window.end, count(*) as cnt FROM VALUES ('A1', '2021-01-01 00:00:00'), ('A1', '2021-01-01 00:04:30'), ('A1', '2021-01-01 00:10:00'), ('A2', '2021-01-01 00:01:00') AS tab(a, b) GROUP by a, session_window(b, '5 minutes') ORDER BY a, start;
  A1    2021-01-01 00:00:00 2021-01-01 00:09:30 2
  A1    2021-01-01 00:10:00 2021-01-01 00:15:00 1
  A2    2021-01-01 00:01:00 2021-01-01 00:06:00 1
> SELECT a, session_window.start, session_window.end, count(*) as cnt FROM VALUES ('A1', '2021-01-01 00:00:00'), ('A1', '2021-01-01 00:04:30'), ('A1', '2021-01-01 00:10:00'), ('A2', '2021-01-01 00:01:00'), ('A2', '2021-01-01 00:04:30') AS tab(a, b) GROUP by a, session_window(b, CASE WHEN a = 'A1' THEN '5 minutes' WHEN a = 'A2' THEN '1 minute' ELSE '10 minutes' END) ORDER BY a, start;
  A1    2021-01-01 00:00:00 2021-01-01 00:09:30 2
  A1    2021-01-01 00:10:00 2021-01-01 00:15:00 1
  A2    2021-01-01 00:01:00 2021-01-01 00:02:00 1
  A2    2021-01-01 00:04:30 2021-01-01 00:05:30 1

自 3.2.0

sha

sha(expr) - 傳回 expr 的 sha1 hash 值，為十六進位字串。

範例

> SELECT sha('Spark');
 85f5955f4b27a9a4c2aab6ffe5d7189fc298b92c

自 1.5.0

sha1

sha1(expr) - 傳回 expr 的 sha1 hash 值，為十六進位字串。

範例

> SELECT sha1('Spark');
 85f5955f4b27a9a4c2aab6ffe5d7189fc298b92c

自 1.5.0

sha2

sha2(expr, bitLength) - 傳回 expr 的 SHA-2 系列檢查和，為十六進位字串。支援 SHA-224、SHA-256、SHA-384 和 SHA-512。0 的位元長度等於 256。

範例

> SELECT sha2('Spark', 256);
 529bc3b07127ecb7e53a4dcf1991d9152c24537d919178022b2c42657f79a26b

自 1.5.0

shiftleft

shiftleft(base, expr) - 位元左移。

範例

> SELECT shiftleft(2, 1);
 4

自 1.5.0

shiftright

shiftright(base, expr) - 位元（有號）右移。

範例

> SELECT shiftright(4, 1);
 2

自 1.5.0

shiftrightunsigned

shiftrightunsigned(base, expr) - 位元無號右移。

範例

> SELECT shiftrightunsigned(4, 1);
 2

自 1.5.0

shuffle

shuffle(array) - 傳回給定陣列的隨機排列。

範例

> SELECT shuffle(array(1, 20, 3, 5));
 [3,1,5,20]
> SELECT shuffle(array(1, 20, null, 3));
 [20,null,3,1]

注意

此函數是非確定性的。

自 2.4.0

sign

sign(expr) - 傳回 -1.0、0.0 或 1.0，expr 為負數、0 或正數。

範例

> SELECT sign(40);
 1.0
> SELECT sign(INTERVAL -'100' YEAR);
 -1.0

自 1.4.0

signum

signum(expr) - 傳回 -1.0、0.0 或 1.0，expr 為負數、0 或正數。

範例

> SELECT signum(40);
 1.0
> SELECT signum(INTERVAL -'100' YEAR);
 -1.0

自 1.4.0

sin

sin(expr) - 傳回 expr 的正弦值，如同由 java.lang.Math.sin 計算。

引數

expr - 以弧度為單位的角度

範例

> SELECT sin(0);
 0.0

自 1.4.0

sinh

sinh(expr) - 傳回 expr 的雙曲正弦值，如同由 java.lang.Math.sinh 計算。

引數

expr - 雙曲角度

範例

> SELECT sinh(0);
 0.0

自 1.4.0

size

size(expr) - 傳回陣列或映射的大小。如果 spark.sql.legacy.sizeOfNull 設為 false 或 spark.sql.ansi.enabled 設為 true，此函數會為 null 輸入傳回 null。否則，此函數會為 null 輸入傳回 -1。在預設設定下，此函數會為 null 輸入傳回 -1。

範例

> SELECT size(array('b', 'd', 'c', 'a'));
 4
> SELECT size(map('a', 1, 'b', 2));
 2

自 1.5.0

skewness

skewness(expr) - 傳回從群組值計算的偏度值。

範例

> SELECT skewness(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);
 1.1135657469022011
> SELECT skewness(col) FROM VALUES (-1000), (-100), (10), (20) AS tab(col);
 -1.1135657469022011

自 1.6.0

slice

slice(x, start, length) - 從索引 start 開始（陣列索引從 1 開始，或如果 start 為負數則從結尾開始）擷取陣列 x，並具有指定的長度。

範例

> SELECT slice(array(1, 2, 3, 4), 2, 2);
 [2,3]
> SELECT slice(array(1, 2, 3, 4), -2, 2);
 [3,4]

自 2.4.0

smallint

smallint(expr) - 將值 expr 轉換為目標資料類型 smallint。

自 2.0.1

some

some(expr) - 如果 expr 的至少一個值為 true，則傳回 true。

範例

> SELECT some(col) FROM VALUES (true), (false), (false) AS tab(col);
 true
> SELECT some(col) FROM VALUES (NULL), (true), (false) AS tab(col);
 true
> SELECT some(col) FROM VALUES (false), (false), (NULL) AS tab(col);
 false

自 3.0.0

sort_array

sort_array(array[, ascendingOrder]) - 根據陣列元素的自然排序順序，以遞增或遞減順序對輸入陣列進行排序。對於 double/float 類型，NaN 大於任何非 NaN 元素。Null 元素會置於遞增順序傳回陣列的開頭或遞減順序傳回陣列的結尾。

範例

> SELECT sort_array(array('b', 'd', null, 'c', 'a'), true);
 [null,"a","b","c","d"]

自 1.5.0

soundex

soundex(str) - 傳回字串的 Soundex 編碼。

範例

> SELECT soundex('Miller');
 M460

自 1.5.0

space

space(n) - 傳回一個包含 n 個空格的字串。

範例

> SELECT concat(space(2), '1');
   1

自 1.5.0

spark_partition_id

spark_partition_id() - 傳回目前的分割 ID。

範例

> SELECT spark_partition_id();
 0

自 1.4.0

split

split(str, regex, limit) - 以符合 regex 的出現位置分割 str，並傳回長度最多為 limit 的陣列

引數

str - 要分割的字串表達式。
regex - 代表正規表達式的字串。regex 字串應為 Java 正規表達式。
limit - 控制正規表達式套用次數的整數表達式。
- limit > 0：結果陣列的長度不會超過 limit，而結果陣列的最後一個項目將包含最後一個匹配的正規表達式之後的所有輸入。
- limit <= 0：regex 將會套用盡可能多次，而結果陣列的大小可以是任何大小。

範例

> SELECT split('oneAtwoBthreeC', '[ABC]');
 ["one","two","three",""]
> SELECT split('oneAtwoBthreeC', '[ABC]', -1);
 ["one","two","three",""]
> SELECT split('oneAtwoBthreeC', '[ABC]', 2);
 ["one","twoBthreeC"]

自 1.5.0

split_part

split_part(str, delimiter, partNum) - 以分隔符號分割 str，並傳回分割的請求部分（以 1 為基準）。如果任何輸入為 null，則傳回 null。如果 partNum 超出分割部分的範圍，則傳回空字串。如果 partNum 為 0，則會擲回錯誤。如果 partNum 為負數，則會從字串結尾向後計算部分。如果 delimiter 為空字串，則不會分割 str。

範例

> SELECT split_part('11.12.13', '.', 3);
 13

自 3.3.0

sqrt

sqrt(expr) - 傳回 expr 的平方根。

範例

> SELECT sqrt(4);
 2.0

自 1.1.1

stack

stack(n, expr1, ..., exprk) - 將 expr1, ..., exprk 分割成 n 列。預設使用欄位名稱 col0、col1 等，除非另有指定。

範例

> SELECT stack(2, 1, 2, 3);
 1  2
 3  NULL

自 2.0.0

startswith

startswith(left, right) - 傳回布林值。如果 left 以 right 開頭，則值為 True。如果任一輸入表達式為 NULL，則傳回 NULL。否則，傳回 False。left 或 right 都必須為字串或二進位類型。

範例

> SELECT startswith('Spark SQL', 'Spark');
 true
> SELECT startswith('Spark SQL', 'SQL');
 false
> SELECT startswith('Spark SQL', null);
 NULL
> SELECT startswith(x'537061726b2053514c', x'537061726b');
 true
> SELECT startswith(x'537061726b2053514c', x'53514c');
 false

自 3.3.0

std

std(expr) - 傳回根據群組值計算的樣本標準差。

範例

> SELECT std(col) FROM VALUES (1), (2), (3) AS tab(col);
 1.0

自 1.6.0

stddev

stddev(expr) - 傳回根據群組值計算的樣本標準差。

範例

> SELECT stddev(col) FROM VALUES (1), (2), (3) AS tab(col);
 1.0

自 1.6.0

stddev_pop

stddev_pop(expr) - 傳回根據群組值計算的母體標準差。

範例

> SELECT stddev_pop(col) FROM VALUES (1), (2), (3) AS tab(col);
 0.816496580927726

自 1.6.0

stddev_samp

stddev_samp(expr) - 傳回根據群組值計算的樣本標準差。

範例

> SELECT stddev_samp(col) FROM VALUES (1), (2), (3) AS tab(col);
 1.0

自 1.6.0

str_to_map

str_to_map(text[, pairDelim[, keyValueDelim]]) - 在使用分隔符號將文字分割成鍵值對後，建立一個對應。預設的 pairDelim 分隔符號為「,」，keyValueDelim 分隔符號為「:」。pairDelim 和 keyValueDelim 都視為正規表示式。

範例

> SELECT str_to_map('a:1,b:2,c:3', ',', ':');
 {"a":"1","b":"2","c":"3"}
> SELECT str_to_map('a');
 {"a":null}

自 2.0.1

string

string(expr) - 將值 expr 轉換成目標資料類型 string。

自 2.0.1

struct

struct(col1, col2, col3, ...) - 使用指定的欄位值建立一個結構。

範例

> SELECT struct(1, 2, 3);
 {"col1":1,"col2":2,"col3":3}

自 1.4.0

substr

substr(str, pos[, len]) - 傳回從 pos 開始且長度為 len 的 str 子字串，或從 pos 開始且長度為 len 的位元組陣列切片。

substr(str FROM pos[ FOR len]]) - 傳回從 pos 開始且長度為 len 的 str 子字串，或從 pos 開始且長度為 len 的位元組陣列切片。

範例

> SELECT substr('Spark SQL', 5);
 k SQL
> SELECT substr('Spark SQL', -3);
 SQL
> SELECT substr('Spark SQL', 5, 1);
 k
> SELECT substr('Spark SQL' FROM 5);
 k SQL
> SELECT substr('Spark SQL' FROM -3);
 SQL
> SELECT substr('Spark SQL' FROM 5 FOR 1);
 k
> SELECT substr(encode('Spark SQL', 'utf-8'), 5);
 k SQL

自 1.5.0

substring

substring(str, pos[, len]) - 傳回從 pos 開始且長度為 len 的 str 子字串，或從 pos 開始且長度為 len 的位元組陣列切片。

substring(str FROM pos[ FOR len]]) - 傳回從 pos 開始且長度為 len 的 str 子字串，或從 pos 開始且長度為 len 的位元組陣列切片。

範例

> SELECT substring('Spark SQL', 5);
 k SQL
> SELECT substring('Spark SQL', -3);
 SQL
> SELECT substring('Spark SQL', 5, 1);
 k
> SELECT substring('Spark SQL' FROM 5);
 k SQL
> SELECT substring('Spark SQL' FROM -3);
 SQL
> SELECT substring('Spark SQL' FROM 5 FOR 1);
 k
> SELECT substring(encode('Spark SQL', 'utf-8'), 5);
 k SQL

自 1.5.0

substring_index

substring_index(str, delim, count) - 傳回從 str 中，在分隔符號 delim 出現 count 次之前，所擷取的子字串。如果 count 為正數，則傳回最後一個分隔符號左邊的所有內容（從左邊算起）。如果 count 為負數，則傳回最後一個分隔符號右邊的所有內容（從右邊算起）。substring_index 函式在搜尋 delim 時會執行大小寫敏感比對。

範例

> SELECT substring_index('www.apache.org', '.', 2);
 www.apache

自 1.5.0

sum

sum(expr) - 傳回從群組值計算出的總和。

範例

> SELECT sum(col) FROM VALUES (5), (10), (15) AS tab(col);
 30
> SELECT sum(col) FROM VALUES (NULL), (10), (15) AS tab(col);
 25
> SELECT sum(col) FROM VALUES (NULL), (NULL) AS tab(col);
 NULL

自 1.0.0

tan

tan(expr) - 傳回 expr 的正切，如同由 java.lang.Math.tan 計算。

引數

expr - 以弧度為單位的角度

範例

> SELECT tan(0);
 0.0

自 1.4.0

tanh

tanh(expr) - 傳回 expr 的雙曲正切，如同由 java.lang.Math.tanh 計算。

引數

expr - 雙曲角度

範例

> SELECT tanh(0);
 0.0

自 1.4.0

timestamp

timestamp(expr) - 將值 expr 轉換為目標資料類型 timestamp。

自 2.0.1

timestamp_micros

timestamp_micros(microseconds) - 從 UTC 紀元以來的微秒數建立時間戳記。

範例

> SELECT timestamp_micros(1230219000123123);
 2008-12-25 07:30:00.123123

自 3.1.0

timestamp_millis

timestamp_millis(milliseconds) - 從 UTC 紀元以來的毫秒數建立時間戳記。

範例

> SELECT timestamp_millis(1230219000123);
 2008-12-25 07:30:00.123

自 3.1.0

timestamp_seconds

timestamp_seconds(seconds) - 從 UTC 紀元以來的秒數（可以是分數）建立時間戳記。

範例

> SELECT timestamp_seconds(1230219000);
 2008-12-25 07:30:00
> SELECT timestamp_seconds(1230219000.123);
 2008-12-25 07:30:00.123

自 3.1.0

tinyint

tinyint(expr) - 將值 expr 轉換為目標資料類型 tinyint。

自 2.0.1

to_binary

to_binary(str[, fmt]) - 根據提供的 fmt，將輸入 str 轉換為二進位值。fmt 可以是不區分大小寫的字串文字「hex」、「utf-8」、「utf8」或「base64」。如果省略 fmt，轉換的二進位格式預設為「hex」。如果至少一個輸入參數為 NULL，函數會傳回 NULL。

範例

> SELECT to_binary('abc', 'utf-8');
 abc

自 3.3.0

to_char

to_char(numberExpr, formatExpr) - 根據 formatExpr，將 numberExpr 轉換為字串。如果轉換失敗，會擲回例外。格式可以包含下列字元（不區分大小寫）：『0』或『9』：指定介於 0 到 9 之間的預期數字。格式字串中的 0 或 9 序列會與輸入值中的數字序列相符，產生與格式字串中對應序列長度相同的結果字串。如果 0/9 序列包含的數字比小數值的對應部分多、以 0 開頭且在小數點之前，結果字串會以 0 左邊對齊。否則，會以空格對齊。『.』或『D』：指定小數點的位置（可選，僅允許一次）。『,』或『G』：指定群組（千位）分隔符號（,）的位置。每個群組分隔符號的左右兩側都必須有 0 或 9。『$』：指定 $ 貨幣符號的位置。此字元只能指定一次。『S』或『MI』：指定 '-' 或 '+' 符號的位置（可選，僅允許在格式字串的開頭或結尾出現一次）。請注意，『S』會為正值印出『+』，但『MI』會印出一個空格。『PR』：僅允許在格式字串的結尾出現；指定如果輸入值為負值，結果字串會以尖括號括起來（『<1>』）。

範例

> SELECT to_char(454, '999');
 454
> SELECT to_char(454.00, '000D00');
 454.00
> SELECT to_char(12454, '99G999');
 12,454
> SELECT to_char(78.12, '$99.99');
 $78.12
> SELECT to_char(-12454.8, '99G999D9S');
 12,454.8-

自 3.4.0

to_csv

to_csv(expr[, options]) - 傳回具有給定結構值之 CSV 字串

範例

> SELECT to_csv(named_struct('a', 1, 'b', 2));
 1,2
> SELECT to_csv(named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd')), map('timestampFormat', 'dd/MM/yyyy'));
 26/08/2015

自 3.0.0

to_date

to_date(date_str[, fmt]) - 使用 fmt 表達式剖析 date_str 表達式為日期。傳回無效輸入的 null。預設情況下，如果省略 fmt，它會遵循轉換規則為日期。

引數

date_str - 要剖析為日期的字串。
fmt - 要遵循的日期格式模式。請參閱日期時間模式以取得有效的日期和時間格式模式。

範例

> SELECT to_date('2009-07-30 04:17:52');
 2009-07-30
> SELECT to_date('2016-12-31', 'yyyy-MM-dd');
 2016-12-31

自 1.5.0

to_json

to_json(expr[, options]) - 傳回具有給定結構值之 JSON 字串

範例

> SELECT to_json(named_struct('a', 1, 'b', 2));
 {"a":1,"b":2}
> SELECT to_json(named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd')), map('timestampFormat', 'dd/MM/yyyy'));
 {"time":"26/08/2015"}
> SELECT to_json(array(named_struct('a', 1, 'b', 2)));
 [{"a":1,"b":2}]
> SELECT to_json(map('a', named_struct('b', 1)));
 {"a":{"b":1}}
> SELECT to_json(map(named_struct('a', 1),named_struct('b', 2)));
 {"[1]":{"b":2}}
> SELECT to_json(map('a', 1));
 {"a":1}
> SELECT to_json(array(map('a', 1)));
 [{"a":1}]

自 2.2.0

to_number

to_number(expr, fmt) - 根據字串格式 'fmt' 將字串 'expr' 轉換為數字。如果轉換失敗，則擲回例外。格式可以包含下列字元，不分大小寫：'0' 或 '9'：指定 0 到 9 之間的預期數字。格式字串中的 0 或 9 順序與輸入字串中的數字順序相符。如果 0/9 順序以 0 開頭且位於小數點之前，則它只能與相同大小的數字順序相符。否則，如果順序以 9 開頭或位於小數點之後，則它可以與具有相同或更小大小的數字順序相符。'.' 或 'D'：指定小數點的位置（選用，僅允許一次）。',' 或 'G'：指定群組（千位數）分隔符的位置（，）。每個群組分隔符的左右兩側都必須有 0 或 9。'expr' 必須與與數字大小相關的群組分隔符相符。'$'：指定 $ 貨幣符號的位置。此字元只能指定一次。'S' 或 'MI'：指定 '-' 或 '+' 符號的位置（選用，僅允許在格式字串的開頭或結尾一次）。請注意，'S' 允許 '-' 但 'MI' 不允許。'PR'：僅允許在格式字串的結尾；指定 'expr' 使用尖括號表示負數。('<1>')。

範例

> SELECT to_number('454', '999');
 454
> SELECT to_number('454.00', '000.00');
 454.00
> SELECT to_number('12,454', '99,999');
 12454
> SELECT to_number('$78.12', '$99.99');
 78.12
> SELECT to_number('12,454.8-', '99,999.9S');
 -12454.8

自 3.3.0

to_timestamp

to_timestamp(timestamp_str[, fmt]) - 使用 fmt 表達式剖析 timestamp_str 表達式為時間戳記。傳回無效輸入的 null。預設情況下，如果省略 fmt，它會遵循轉換規則為時間戳記。結果資料類型與設定檔 spark.sql.timestampType 的值一致。

引數

timestamp_str - 要剖析為時間戳記的字串。
fmt - 要遵循的時間戳記格式模式。請參閱日期時間模式以取得有效的日期和時間格式模式。

範例

> SELECT to_timestamp('2016-12-31 00:12:00');
 2016-12-31 00:12:00
> SELECT to_timestamp('2016-12-31', 'yyyy-MM-dd');
 2016-12-31 00:00:00

自 2.2.0

to_timestamp_ltz

to_timestamp_ltz(timestamp_str[, fmt]) - 使用 fmt 表達式解析 timestamp_str 表達式，以取得具有當地時區的時間戳記。如果輸入無效，則傳回 null。如果省略 fmt，它會遵循轉型規則轉換為時間戳記。

引數

timestamp_str - 要解析為具有當地時區的時間戳記的字串。
fmt - 要遵循的時間戳記格式模式。請參閱日期時間模式以取得有效的日期和時間格式模式。

範例

> SELECT to_timestamp_ltz('2016-12-31 00:12:00');
 2016-12-31 00:12:00
> SELECT to_timestamp_ltz('2016-12-31', 'yyyy-MM-dd');
 2016-12-31 00:00:00

自 3.4.0

to_timestamp_ntz

to_timestamp_ntz(timestamp_str[, fmt]) - 使用 fmt 表達式解析 timestamp_str 表達式，以取得不帶時區的時間戳記。如果輸入無效，則傳回 null。如果省略 fmt，它會遵循轉型規則轉換為時間戳記。

引數

timestamp_str - 要解析為不帶時區的時間戳記的字串。
fmt - 要遵循的時間戳記格式模式。請參閱日期時間模式以取得有效的日期和時間格式模式。

範例

> SELECT to_timestamp_ntz('2016-12-31 00:12:00');
 2016-12-31 00:12:00
> SELECT to_timestamp_ntz('2016-12-31', 'yyyy-MM-dd');
 2016-12-31 00:00:00

自 3.4.0

to_unix_timestamp

to_unix_timestamp(timeExp[, fmt]) - 傳回指定時間的 UNIX 時間戳記。

引數

timeExp - 日期/時間戳記或字串，會傳回為 UNIX 時間戳記。
fmt - 要遵循的日期/時間格式模式。如果 timeExp 不是字串，則會略過。預設值為「yyyy-MM-dd HH:mm:ss」。請參閱日期時間模式，以取得有效的日期和時間格式模式。

範例

> SELECT to_unix_timestamp('2016-04-08', 'yyyy-MM-dd');
 1460098800

自 1.6.0

to_utc_timestamp

to_utc_timestamp(timestamp, timezone) - 給定一個類似「2017-07-14 02:40:00.0」的時間戳記，將其解釋為指定時區的時間，並將該時間轉換為 UTC 的時間戳記。例如，「GMT+1」會產生「2017-07-14 01:40:00.0」。

範例

> SELECT to_utc_timestamp('2016-08-31', 'Asia/Seoul');
 2016-08-30 15:00:00

自 1.5.0

to_varchar

to_varchar(numberExpr, formatExpr) - 根據 formatExpr 將 numberExpr 轉換為字串。如果轉換失敗，則會擲回例外。格式可以包含下列字元（不分大小寫）：「0」或「9」：指定介於 0 到 9 之間的預期數字。格式字串中的 0 或 9 序列會比對輸入值中的數字序列，產生與格式字串中對應序列長度相同的結果字串。如果 0/9 序列包含比小數值對應部分更多的數字、以 0 開頭，且位於小數點之前，則會在結果字串左側補上 0。否則，會補上空白。「.」或「D」：指定小數點的位置（選用，僅允許一次）。「,」或「G」：指定群組（千位）分隔符號（,）的位置。每個群組分隔符號的左右兩側都必須有 0 或 9。「$」：指定 $ 貨幣符號的位置。此字元僅能指定一次。「S」或「MI」：指定「-」或「+」符號的位置（選用，僅允許在格式字串的開頭或結尾出現一次）。請注意，「S」會對正值印出「+」，但「MI」會印出空白。「PR」：僅允許出現在格式字串的結尾；指定如果輸入值為負值，則會將結果字串用尖括號包起來（「<1>」）。

範例

> SELECT to_varchar(454, '999');
 454
> SELECT to_varchar(454.00, '000D00');
 454.00
> SELECT to_varchar(12454, '99G999');
 12,454
> SELECT to_varchar(78.12, '$99.99');
 $78.12
> SELECT to_varchar(-12454.8, '99G999D9S');
 12,454.8-

自 3.5.0

transform

transform(expr, func) - 使用函式轉換陣列中的元素。

範例

> SELECT transform(array(1, 2, 3), x -> x + 1);
 [2,3,4]
> SELECT transform(array(1, 2, 3), (x, i) -> x + i);
 [1,3,5]

自 2.4.0

transform_keys

transform_keys(expr, func) - 使用函數轉換地圖中的元素。

範例

> SELECT transform_keys(map_from_arrays(array(1, 2, 3), array(1, 2, 3)), (k, v) -> k + 1);
 {2:1,3:2,4:3}
> SELECT transform_keys(map_from_arrays(array(1, 2, 3), array(1, 2, 3)), (k, v) -> k + v);
 {2:1,4:2,6:3}

自 3.0.0

transform_values

transform_values(expr, func) - 使用函數轉換地圖中的值。

範例

> SELECT transform_values(map_from_arrays(array(1, 2, 3), array(1, 2, 3)), (k, v) -> v + 1);
 {1:2,2:3,3:4}
> SELECT transform_values(map_from_arrays(array(1, 2, 3), array(1, 2, 3)), (k, v) -> k + v);
 {1:2,2:4,3:6}

自 3.0.0

translate

translate(input, from, to) - 透過將 input 字串中存在於 from 字串中的字元替換為 to 字串中的對應字元，來轉譯 input 字串。

範例

> SELECT translate('AaBbCc', 'abc', '123');
 A1B2C3

自 1.5.0

trim

trim(str) - 從 str 中移除前導和尾隨的空白字元。

trim(BOTH FROM str) - 從 str 中移除前導和尾隨的空白字元。

trim(LEADING FROM str) - 從 str 中移除前導的空白字元。

trim(TRAILING FROM str) - 從 str 中移除尾隨的空白字元。

trim(trimStr FROM str) - 從 str 中移除前導和尾隨的 trimStr 字元。

trim(BOTH trimStr FROM str) - 從 str 中移除前導和尾隨的 trimStr 字元。

trim(LEADING trimStr FROM str) - 從 str 中移除前導的 trimStr 字元。

trim(TRAILING trimStr FROM str) - 從 str 中移除尾隨的 trimStr 字元。

引數

str - 字串表達式
trimStr - 要修剪的修剪字串字元，預設值為單一空白
BOTH, FROM - 這些是關鍵字，用於指定從字串兩端修剪字串字元
LEADING, FROM - 這些是關鍵字，用於指定從字串左端修剪字串字元
TRAILING, FROM - 這些是關鍵字，用於指定從字串右端修剪字串字元

範例

> SELECT trim('    SparkSQL   ');
 SparkSQL
> SELECT trim(BOTH FROM '    SparkSQL   ');
 SparkSQL
> SELECT trim(LEADING FROM '    SparkSQL   ');
 SparkSQL
> SELECT trim(TRAILING FROM '    SparkSQL   ');
     SparkSQL
> SELECT trim('SL' FROM 'SSparkSQLS');
 parkSQ
> SELECT trim(BOTH 'SL' FROM 'SSparkSQLS');
 parkSQ
> SELECT trim(LEADING 'SL' FROM 'SSparkSQLS');
 parkSQLS
> SELECT trim(TRAILING 'SL' FROM 'SSparkSQLS');
 SSparkSQ

自 1.5.0

trunc

trunc(date, fmt) - 傳回 date，其時間部分已根據格式模型 fmt 指定的單位進行截斷。

引數

date - 日期值或有效的日期字串
fmt - 代表要截斷到的單位的格式
- "YEAR", "YYYY", "YY" - 截斷至 date 所屬年份的第一個日期
- "QUARTER" - 截斷至 date 所屬季度的第一個日期
- "MONTH", "MM", "MON" - 截斷至 date 所屬月份的第一個日期
- "WEEK" - 截斷至 date 所屬星期中的星期一

範例

> SELECT trunc('2019-08-04', 'week');
 2019-07-29
> SELECT trunc('2019-08-04', 'quarter');
 2019-07-01
> SELECT trunc('2009-02-12', 'MM');
 2009-02-01
> SELECT trunc('2015-10-27', 'YEAR');
 2015-01-01

自 1.5.0

try_add

try_add(expr1, expr2) - 傳回 expr1 和 expr2 的總和，如果溢位，結果為 null。可接受的輸入類型與 + 運算子相同。

範例

> SELECT try_add(1, 2);
 3
> SELECT try_add(2147483647, 1);
 NULL
> SELECT try_add(date'2021-01-01', 1);
 2021-01-02
> SELECT try_add(date'2021-01-01', interval 1 year);
 2022-01-01
> SELECT try_add(timestamp'2021-01-01 00:00:00', interval 1 day);
 2021-01-02 00:00:00
> SELECT try_add(interval 1 year, interval 2 year);
 3-0

自 3.2.0

try_aes_decrypt

try_aes_decrypt(expr, key[, mode[, padding[, aad]]]) - 這是 aes_decrypt 的特殊版本，它執行相同的操作，但如果無法執行解密，則傳回 NULL 值，而不是引發錯誤。

範例

> SELECT try_aes_decrypt(unhex('6E7CA17BBB468D3084B5744BCA729FB7B2B7BCB8E4472847D02670489D95FA97DBBA7D3210'), '0000111122223333', 'GCM');
 Spark SQL
> SELECT try_aes_decrypt(unhex('----------468D3084B5744BCA729FB7B2B7BCB8E4472847D02670489D95FA97DBBA7D3210'), '0000111122223333', 'GCM');
 NULL

自 3.5.0

try_avg

try_avg(expr) - 傳回從群組值計算的平均值，如果溢位，結果為 null。

範例

> SELECT try_avg(col) FROM VALUES (1), (2), (3) AS tab(col);
 2.0
> SELECT try_avg(col) FROM VALUES (1), (2), (NULL) AS tab(col);
 1.5
> SELECT try_avg(col) FROM VALUES (interval '2147483647 months'), (interval '1 months') AS tab(col);
 NULL

自 3.3.0

try_divide

try_divide(被除數, 除數) - 傳回 被除數/除數。它總是執行浮點數除法。如果 expr2 為 0，其結果永遠為 null。被除數必須是數字或區間。除數必須是數字。

範例

> SELECT try_divide(3, 2);
 1.5
> SELECT try_divide(2L, 2L);
 1.0
> SELECT try_divide(1, 0);
 NULL
> SELECT try_divide(interval 2 month, 2);
 0-1
> SELECT try_divide(interval 2 month, 0);
 NULL

自 3.2.0

try_element_at

try_element_at(陣列, 索引) - 傳回陣列中位於給定 (以 1 為基底) 索引的元素。如果索引為 0，Spark 會擲回錯誤。如果索引 < 0，則從最後一個元素存取到第一個元素。如果索引超過陣列長度，函數永遠傳回 NULL。

try_element_at(映射, 鍵) - 傳回給定鍵的值。如果映射中不包含該鍵，函數永遠傳回 NULL。

範例

> SELECT try_element_at(array(1, 2, 3), 2);
 2
> SELECT try_element_at(map(1, 'a', 2, 'b'), 2);
 b

自 3.3.0

try_multiply

try_multiply(expr1, expr2) - 傳回 expr1*expr2，結果在溢位時為 null。可接受的輸入類型與 * 算子相同。

範例

> SELECT try_multiply(2, 3);
 6
> SELECT try_multiply(-2147483648, 10);
 NULL
> SELECT try_multiply(interval 2 year, 3);
 6-0

自 3.3.0

try_subtract

try_subtract(expr1, expr2) - 傳回 expr1-expr2，結果在溢位時為 null。可接受的輸入類型與 - 算子相同。

範例

> SELECT try_subtract(2, 1);
 1
> SELECT try_subtract(-2147483648, 1);
 NULL
> SELECT try_subtract(date'2021-01-02', 1);
 2021-01-01
> SELECT try_subtract(date'2021-01-01', interval 1 year);
 2020-01-01
> SELECT try_subtract(timestamp'2021-01-02 00:00:00', interval 1 day);
 2021-01-01 00:00:00
> SELECT try_subtract(interval 2 year, interval 1 year);
 1-0

自 3.3.0

try_sum

try_sum(expr) - 傳回從群組值計算出的總和，結果在溢位時為 null。

範例

> SELECT try_sum(col) FROM VALUES (5), (10), (15) AS tab(col);
 30
> SELECT try_sum(col) FROM VALUES (NULL), (10), (15) AS tab(col);
 25
> SELECT try_sum(col) FROM VALUES (NULL), (NULL) AS tab(col);
 NULL
> SELECT try_sum(col) FROM VALUES (9223372036854775807L), (1L) AS tab(col);
 NULL

自 3.3.0

try_to_binary

try_to_binary(字串[, 格式]) - 這是 to_binary 的特殊版本，執行相同的運算，但如果無法執行轉換，則傳回 NULL 值，而不是擲回錯誤。

範例

> SELECT try_to_binary('abc', 'utf-8');
 abc
> select try_to_binary('a!', 'base64');
 NULL
> select try_to_binary('abc', 'invalidFormat');
 NULL

自 3.3.0

try_to_number

try_to_number(expr, 格式) - 根據字串格式 fmt 將字串 'expr' 轉換為數字。如果字串 'expr' 與預期的格式不符，則傳回 NULL。格式遵循與 to_number 函數相同的語意。

範例

> SELECT try_to_number('454', '999');
 454
> SELECT try_to_number('454.00', '000.00');
 454.00
> SELECT try_to_number('12,454', '99,999');
 12454
> SELECT try_to_number('$78.12', '$99.99');
 78.12
> SELECT try_to_number('12,454.8-', '99,999.9S');
 -12454.8

自 3.3.0

try_to_timestamp

try_to_timestamp(時間戳記字串[, 格式]) - 使用 fmt 表達式將 時間戳記字串 表達式解析為時間戳記。在啟用/停用 ANSI SQL 模式時，函數在無效輸入時永遠傳回 null。預設情況下，如果省略 fmt，它會遵循轉換為時間戳記的規則。結果資料類型與設定檔 spark.sql.timestampType 的值一致。

引數

timestamp_str - 要剖析為時間戳記的字串。
fmt - 要遵循的時間戳記格式模式。請參閱日期時間模式以取得有效的日期和時間格式模式。

範例

> SELECT try_to_timestamp('2016-12-31 00:12:00');
 2016-12-31 00:12:00
> SELECT try_to_timestamp('2016-12-31', 'yyyy-MM-dd');
 2016-12-31 00:00:00
> SELECT try_to_timestamp('foo', 'yyyy-MM-dd');
 NULL

自 3.4.0

typeof

typeof(expr) - 為輸入的資料類型傳回 DDL 格式的類型字串。

範例

> SELECT typeof(1);
 int
> SELECT typeof(array(1));
 array<int>

自 3.0.0

ucase

ucase(字串) - 傳回將所有字元都轉換為大寫的 字串。

範例

> SELECT ucase('SparkSql');
 SPARKSQL

自 1.0.1

unbase64

unbase64(字串) - 將參數從 base 64 字串 字串 轉換為二進位。

範例

> SELECT unbase64('U3BhcmsgU1FM');
 Spark SQL

自 1.5.0

unhex

unhex(expr) - 將十六進位 expr 轉換為二進位。

範例

> SELECT decode(unhex('537061726B2053514C'), 'UTF-8');
 Spark SQL

自 1.5.0

unix_date

unix_date(日期) - 傳回自 1970-01-01 以來的日數。

範例

> SELECT unix_date(DATE("1970-01-02"));
 1

自 3.1.0

unix_micros

unix_micros(時間戳記) - 傳回自 1970-01-01 00:00:00 UTC 以來的微秒數。

範例

> SELECT unix_micros(TIMESTAMP('1970-01-01 00:00:01Z'));
 1000000

自 3.1.0

unix_millis

unix_millis(時間戳記) - 傳回自 1970-01-01 00:00:00 UTC 以來的毫秒數。截斷較高精度的層級。

範例

> SELECT unix_millis(TIMESTAMP('1970-01-01 00:00:01Z'));
 1000

自 3.1.0

unix_seconds

unix_seconds(時間戳記) - 傳回自 1970-01-01 00:00:00 UTC 以來的秒數。截斷較高精度的層級。

範例

> SELECT unix_seconds(TIMESTAMP('1970-01-01 00:00:01Z'));
 1

自 3.1.0

unix_timestamp

unix_timestamp([時間表達式[, 格式]]) - 傳回目前或指定時間的 UNIX 時間戳記。

引數

時間表達式 - 日期/時間戳記或字串。如果未提供，預設為目前時間。
格式 - 要遵循的日期/時間格式模式。如果 時間表達式 不是字串，則會略過。預設值為「yyyy-MM-dd HH:mm:ss」。有關有效的日期和時間格式模式，請參閱日期時間模式。

範例

> SELECT unix_timestamp();
 1476884637
> SELECT unix_timestamp('2016-04-08', 'yyyy-MM-dd');
 1460041200

自 1.5.0

upper

upper(字串) - 傳回將所有字元都變更為大寫的 字串。

範例

> SELECT upper('SparkSql');
 SPARKSQL

自 1.0.1

url_decode

url_decode(字串) - 使用特定編碼方案，以「application/x-www-form-urlencoded」格式解碼 字串。

引數

字串 - 要解碼的字串表達式

範例

> SELECT url_decode('https%3A%2F%2Fspark.apache.org');
 https://spark.dev.org.tw

自 3.4.0

url_encode

url_encode(字串) - 使用特定編碼方案，將字串轉換為「application/x-www-form-urlencoded」格式。

引數

字串 - 要轉換的字串表達式

範例

> SELECT url_encode('https://spark.dev.org.tw');
 https%3A%2F%2Fspark.apache.org

自 3.4.0

user

user() - 目前執行內容的使用者名稱。

範例

> SELECT user();
 mockingjay

自 3.2.0

uuid

uuid() - 傳回通用唯一識別碼 (UUID) 字串。值傳回為標準 UUID 36 字元字串。

範例

> SELECT uuid();
 46707d92-02f4-4817-8116-a4c3b23e6266

注意

此函數是非確定性的。

自 2.3.0

var_pop

var_pop(表達式) - 傳回根據群組值計算的母體變異數。

範例

> SELECT var_pop(col) FROM VALUES (1), (2), (3) AS tab(col);
 0.6666666666666666

自 1.6.0

var_samp

var_samp(表達式) - 傳回根據群組值計算的樣本變異數。

範例

> SELECT var_samp(col) FROM VALUES (1), (2), (3) AS tab(col);
 1.0

自 1.6.0

variance

variance(表達式) - 傳回根據群組值計算的樣本變異數。

範例

> SELECT variance(col) FROM VALUES (1), (2), (3) AS tab(col);
 1.0

自 1.6.0

version

version() - 傳回 Spark 版本。字串包含 2 個欄位，第一個是發行版本，第二個是 git 修訂版本。

範例

> SELECT version();
 3.1.0 a6d6ea3efedbad14d99c24143834cd4e2e52fb40

自 3.0.0

星期

weekday(日期) - 傳回日期/時間戳記的星期幾 (0 = 星期一，1 = 星期二，...，6 = 星期日)。

範例

> SELECT weekday('2009-07-30');
 3

自 2.4.0

週OfYear

weekofyear(日期) - 傳回指定日期的星期幾。星期從星期一開始，而星期 1 是有 >3 天的第一個星期。

範例

> SELECT weekofyear('2008-02-20');
 8

自 1.5.0

何時

CASE WHEN 表達式1 THEN 表達式2 [WHEN 表達式3 THEN 表達式4]* [ELSE 表達式5] END - 當 表達式1 = true 時，傳回 表達式2；否則，當 表達式3 = true 時，傳回 表達式4；否則，傳回 表達式5。

引數

表達式1、表達式3 - 分支條件表達式都應該是布林型別。
表達式2、表達式4、表達式5 - 分支值表達式和 else 值表達式都應該是相同型別，或可以轉換為共用型別。

範例

> SELECT CASE WHEN 1 > 0 THEN 1 WHEN 2 > 0 THEN 2.0 ELSE 1.2 END;
 1.0
> SELECT CASE WHEN 1 < 0 THEN 1 WHEN 2 > 0 THEN 2.0 ELSE 1.2 END;
 2.0
> SELECT CASE WHEN 1 < 0 THEN 1 WHEN 2 < 0 THEN 2.0 END;
 NULL

自 1.0.1

寬度分組

width_bucket(值、最小值、最大值、區段數) - 傳回 值 在等寬直方圖中會被指定到的區段編號，區段數為 區段數，範圍為 最小值 到 最大值。

範例

> SELECT width_bucket(5.3, 0.2, 10.6, 5);
 3
> SELECT width_bucket(-2.1, 1.3, 3.4, 3);
 0
> SELECT width_bucket(8.1, 0.0, 5.7, 4);
 5
> SELECT width_bucket(-0.9, 5.2, 0.5, 2);
 3
> SELECT width_bucket(INTERVAL '0' YEAR, INTERVAL '0' YEAR, INTERVAL '10' YEAR, 10);
 1
> SELECT width_bucket(INTERVAL '1' YEAR, INTERVAL '0' YEAR, INTERVAL '10' YEAR, 10);
 2
> SELECT width_bucket(INTERVAL '0' DAY, INTERVAL '0' DAY, INTERVAL '10' DAY, 10);
 1
> SELECT width_bucket(INTERVAL '1' DAY, INTERVAL '0' DAY, INTERVAL '10' DAY, 10);
 2

自 3.1.0

視窗

window(time_column, window_duration[, slide_duration[, start_time]]) - 將列中的時間戳指定給予一個或多個時間視窗中的列分組。視窗開始時間包含在內，但結束時間不包含，例如 12:05 會在 [12:05,12:10) 視窗中，但不在 [12:00,12:05) 中。視窗支援微秒精確度。不支援月份順序的視窗。請參閱結構化串流指南文件中的「事件時間視窗操作」以取得詳細說明和範例：https://spark.dev.org.tw/docs/latest/structured-streaming-programming-guide.html#window-operations-on-event-time

引數

time_column - 欄位或表達式，用作依時間視窗化的時間戳記。時間欄位必須為 TimestampType。
window_duration - 指定視窗寬度的字串，表示為「區間值」。（請參閱區間文字以取得更多詳細資料。）請注意，持續時間是固定長度的時間，不會根據行事曆隨時間而改變。
slide_duration - 指定視窗滑動區間的字串，表示為「區間值」。每隔 slide_duration 會產生一個新的視窗。必須小於或等於 window_duration。此持續時間同樣是絕對的，不會根據行事曆而改變。
start_time - 相對於 1970-01-01 00:00:00 UTC 的偏移量，用於開始視窗區間。例如，為了讓每小時翻滾視窗從每小時的 15 分鐘後開始，例如 12:15-13:15、13:15-14:15...，請提供 start_time 為 15 分鐘。

範例

> SELECT a, window.start, window.end, count(*) as cnt FROM VALUES ('A1', '2021-01-01 00:00:00'), ('A1', '2021-01-01 00:04:30'), ('A1', '2021-01-01 00:06:00'), ('A2', '2021-01-01 00:01:00') AS tab(a, b) GROUP by a, window(b, '5 minutes') ORDER BY a, start;
  A1    2021-01-01 00:00:00 2021-01-01 00:05:00 2
  A1    2021-01-01 00:05:00 2021-01-01 00:10:00 1
  A2    2021-01-01 00:00:00 2021-01-01 00:05:00 1
> SELECT a, window.start, window.end, count(*) as cnt FROM VALUES ('A1', '2021-01-01 00:00:00'), ('A1', '2021-01-01 00:04:30'), ('A1', '2021-01-01 00:06:00'), ('A2', '2021-01-01 00:01:00') AS tab(a, b) GROUP by a, window(b, '10 minutes', '5 minutes') ORDER BY a, start;
  A1    2020-12-31 23:55:00 2021-01-01 00:05:00 2
  A1    2021-01-01 00:00:00 2021-01-01 00:10:00 3
  A1    2021-01-01 00:05:00 2021-01-01 00:15:00 1
  A2    2020-12-31 23:55:00 2021-01-01 00:05:00 1
  A2    2021-01-01 00:00:00 2021-01-01 00:10:00 1

自 2.0.0

視窗時間

window_time(window_column) - 從時間/工作階段視窗欄位中擷取時間值，可用於視窗的事件時間值。擷取的時間為 (window.end - 1)，這反映了聚合視窗具有排他性上限 - [start, end) 的事實。請參閱結構化串流指南文件中的「事件時間視窗操作」以取得詳細說明和範例：https://spark.dev.org.tw/docs/latest/structured-streaming-programming-guide.html#window-operations-on-event-time

引數

window_column - 代表時間/工作階段視窗的欄位。

範例

> SELECT a, window.start as start, window.end as end, window_time(window), cnt FROM (SELECT a, window, count(*) as cnt FROM VALUES ('A1', '2021-01-01 00:00:00'), ('A1', '2021-01-01 00:04:30'), ('A1', '2021-01-01 00:06:00'), ('A2', '2021-01-01 00:01:00') AS tab(a, b) GROUP by a, window(b, '5 minutes') ORDER BY a, window.start);
  A1    2021-01-01 00:00:00 2021-01-01 00:05:00 2021-01-01 00:04:59.999999  2
  A1    2021-01-01 00:05:00 2021-01-01 00:10:00 2021-01-01 00:09:59.999999  1
  A2    2021-01-01 00:00:00 2021-01-01 00:05:00 2021-01-01 00:04:59.999999  1

自 3.4.0

xpath

xpath(xml, xpath) - 傳回與 XPath 表達式相符的 xml 節點中的值字串陣列。

範例

> SELECT xpath('<a><b>b1</b><b>b2</b><b>b3</b><c>c1</c><c>c2</c></a>','a/b/text()');
 ["b1","b2","b3"]

自 2.0.0

xpath_boolean

xpath_boolean(xml, xpath) - 如果 XPath 表達式評估為 true，或找到相符的節點，則傳回 true。

範例

> SELECT xpath_boolean('<a><b>1</b></a>','a/b');
 true

自 2.0.0

xpath_double

xpath_double(xml, xpath) - 傳回一個雙精度值，如果找不到相符項，則傳回零值，如果找到相符項但值是非數字，則傳回 NaN。

範例

> SELECT xpath_double('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3.0

自 2.0.0

xpath_float

xpath_float(xml, xpath) - 傳回一個浮點值，如果找不到相符項，則傳回零值，如果找到相符項但值是非數字，則傳回 NaN。

範例

> SELECT xpath_float('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3.0

自 2.0.0

xpath_int

xpath_int(xml, xpath) - 傳回整數值，或在找不到相符項或找到相符項但值是非數字時傳回值零。

範例

> SELECT xpath_int('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3

自 2.0.0

xpath_long

xpath_long(xml, xpath) - 傳回長整數值，或在找不到相符項或找到相符項但值是非數字時傳回值零。

範例

> SELECT xpath_long('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3

自 2.0.0

xpath_number

xpath_number(xml, xpath) - 傳回雙精度值，或在找不到相符項時傳回值零，或在找到相符項但值是非數字時傳回 NaN。

範例

> SELECT xpath_number('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3.0

自 2.0.0

xpath_short

xpath_short(xml, xpath) - 傳回短整數值，或在找不到相符項或找到相符項但值是非數字時傳回值零。

範例

> SELECT xpath_short('<a><b>1</b><b>2</b></a>', 'sum(a/b)');
 3

自 2.0.0

xpath_string

xpath_string(xml, xpath) - 傳回與 XPath 表達式相符的第一個 xml 節點的文字內容。

範例

> SELECT xpath_string('<a><b>b</b><c>cc</c></a>','a/c');
 cc

自 2.0.0

xxhash64

xxhash64(expr1, expr2, ...) - 傳回引數的 64 位元雜湊值。雜湊種子為 42。

範例

> SELECT xxhash64('Spark', array(123), 2);
 5602566077635097486

自 3.0.0

年

year(date) - 傳回日期/時間戳記的年份元件。

範例

> SELECT year('2016-07-30');
 2016

自 1.5.0

zip_with

zip_with(left, right, func) - 使用函式將兩個指定的陣列逐一元素合併成單一陣列。如果一個陣列較短，則在較長陣列的尾端附加 null 以符合長度，然後再套用函式。

範例

> SELECT zip_with(array(1, 2, 3), array('a', 'b', 'c'), (x, y) -> (y, x));
 [{"y":"a","x":1},{"y":"b","x":2},{"y":"c","x":3}]
> SELECT zip_with(array(1, 2), array(3, 4), (x, y) -> x + y);
 [4,6]
> SELECT zip_with(array('a', 'b', 'c'), array('d', 'e', 'f'), (x, y) -> concat(x, y));
 ["ad","be","cf"]

自 2.4.0

|

expr1 | expr2 - 傳回 expr1 和 expr2 的按位元 OR 結果。

範例

> SELECT 3 | 5;
 7

自 1.4.0

||

expr1 || expr2 - 傳回 expr1 和 expr2 的串接。

範例

> SELECT 'Spark' || 'SQL';
 SparkSQL
> SELECT array(1, 2, 3) || array(4, 5) || array(6);
 [1,2,3,4,5,6]

注意

陣列的 || 自 2.4.0 起可用。

自 2.3.0

~

~ expr - 傳回 expr 的按位元 NOT 結果。

範例

> SELECT ~ 0;
 -1

自 1.4.0