内置函数

<<

base << exp - 按位左移。

示例

> SELECT shiftleft(2, 1);
 4
> SELECT 2 << 1;
 4

注意

<< 运算符在 Spark 4.0.0 中作为 shiftleft 的别名添加。

自 4.0.0

>>

base >> expr - 按位（有符号）右移。

示例

> SELECT shiftright(4, 1);
 2
> SELECT 4 >> 1;
 2

注意

>> 运算符在 Spark 4.0.0 中作为 shiftright 的别名添加。

自 4.0.0

>>>

base >>> expr - 按位无符号右移。

示例

> SELECT shiftrightunsigned(4, 1);
 2
> SELECT 4 >>> 1;
 2

注意

>>> 运算符在 Spark 4.0.0 中作为 shiftrightunsigned 的别名添加。

自 4.0.0

aes_decrypt(expr, key[, mode[, padding[, aad]]]) - 使用AES在给定mode和padding下解密expr。支持16、24和32位的密钥长度。支持的（mode，padding）组合有（'ECB'，'PKCS'），（'GCM'，'NONE'）和（'CBC'，'PKCS'）。可选的附加认证数据（AAD）仅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'）。可选的初始化向量（IVs）仅CBC和GCM模式支持。CBC模式必须是16字节，GCM模式必须是12字节。如果未提供，将生成一个随机向量并附加到输出。可选的附加认证数据（AAD）仅GCM模式支持。如果加密时提供了AAD，则解密时必须提供相同的AAD值。默认模式为GCM。

参数

expr - 要加密的二进制值。
key - 用于加密数据的密码。
mode - 指定用于加密消息的分组密码模式。有效模式：ECB、GCM、CBC。
padding - 指定如何填充长度不是块大小倍数的消息。有效值：PKCS、NONE、DEFAULT。DEFAULT填充表示ECB使用PKCS，GCM使用NONE，CBC使用PKCS。
iv - 可选的初始化向量。仅CBC和GCM模式支持。有效值：None 或 ''。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 - 逻辑与。

示例

> 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，则只返回非空值。

示例

> 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的近似percentile，它是col有序值（从最小到最大排序）中的最小S值，使得不超过percentage的col值小于或等于该S值。percentage的值必须在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。

示例

> 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) - 从数组中移除空值。

示例

> 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]) - 使用分隔符和可选的字符串替换空值来连接给定数组的元素。如果未设置nullReplacement的值，则任何空值都将被过滤。

示例

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

示例

> 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) - 返回包含元素count次的数组。

示例

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

自 2.4.0

array_size

array_size(expr) - 返回数组的大小。对于空输入，该函数返回null。

示例

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

自 3.3.0

array_sort

array_sort(expr, func) - 对输入数组进行排序。如果func省略，则按升序排序。输入数组的元素必须是可排序的。对于double/float类型，NaN大于任何非NaN元素。空元素将放在返回数组的末尾。从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包含至少一个也在a2中存在的非空元素，则返回true。如果两个数组没有共同元素，并且它们都非空，并且其中任何一个包含空元素，则返回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 [, message]) - 如果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

input [NOT] between lower AND upper - 评估input是否[不]在lower和upper之间

参数

input - 用于与下限和上限进行比较的表达式。
lower - 介于检查的下限。
upper - 介于检查的上限。

示例

> SELECT 0.5 between 0.1 AND 1.0;
  true

自 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。

示例

> 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）。位置从右到左编号，从零开始。位置参数不能为负数。

示例

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

示例

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

自 3.0.0

bit_xor

bit_xor(expr) - 返回所有非空输入值的按位异或结果，如果都为空则返回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) - 返回一个位图，该位图是子表达式中所有位图的按位或结果。输入应该是从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.ansi.enabled为false且spark.sql.legacy.sizeOfNull为true时，此函数才对空输入返回-1。否则，对空输入返回null。在默认设置下，该函数对空输入返回null。

示例

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

自 2.4.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。也支持expr :: type的替代转换语法。

示例

> SELECT cast('10' as int);
 10
> SELECT '10' :: 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

自 2.3.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

自 2.3.0

chr

chr(expr) - 返回二进制等效于expr的ASCII字符。如果n大于256，则结果等同于chr(n % 256)。

示例

> SELECT chr(65);
 A

自 2.3.0

coalesce

coalesce(expr1, expr2, ...) - 如果存在，则返回第一个非空参数。否则返回null。

示例

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

自 1.0.0

collate

collate(expr, collationName) - 使用指定的排序规则标记给定表达式。

参数

expr - 用于执行排序的字符串表达式。
collationName - 可折叠的字符串表达式，指定排序规则名称。

示例

> SELECT COLLATION('Spark SQL' collate UTF8_LCASE);
SYSTEM.BUILTIN.UTF8_LCASE

自 4.0.0

collation

collation(expr) - 返回给定表达式的排序规则名称。

参数

expr - 用于执行排序的字符串表达式。

示例

> SELECT collation('Spark SQL');
SYSTEM.BUILTIN.UTF8_BINARY

自 4.0.0

collations

collations() - 获取所有Spark SQL字符串排序规则

示例

> SELECT * FROM collations() WHERE NAME = 'UTF8_BINARY';
 SYSTEM  BUILTIN  UTF8_BINARY NULL  NULL  ACCENT_SENSITIVE  CASE_SENSITIVE  NO_PAD  NULL

自 4.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分隔的字符串的连接，跳过空值。

示例

> 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都必须是STRING或BINARY类型。

示例

> 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...]) - 返回所有提供的表达式都非空的行数。

count(DISTINCT expr[, expr...]) - 返回提供的表达式唯一且非空的行数。

示例

> 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、confidence和seed的列的count-min sketch。结果是字节数组，使用前可以反序列化为CountMinSketch。Count-min sketch是一种概率数据结构，用于使用亚线性空间进行基数估计。

示例

> 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

自 3.4.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的字符串值。

参数

timestamp - 要转换为给定格式的日期/时间戳或字符串。
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

dayname

dayname(date) - 返回给定日期的三字母缩写日名称。

示例

> SELECT dayname(DATE('2008-02-20'));
 Wed

自 4.0.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) - 使用第二个参数字符集解码第一个参数。如果任一参数为null，结果也将为null。

decode(expr, search, result [, search, result ] ... [, default]) - 按顺序将expr与每个搜索值进行比较。如果expr等于搜索值，则decode返回相应的result。如果没有找到匹配项，则返回default。如果default省略，则返回null。

参数

bin - 要解码的二进制表达式
charset - 'US-ASCII', 'ISO-8859-1', 'UTF-8', 'UTF-16BE', 'UTF-16LE', 'UTF-16', 'UTF-32'中的一个字符集，用于将bin解码为STRING。它不区分大小写。

示例

> 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

注意

decode(expr, search, result [, search, result ] ... [, default]) 自3.2.0版本开始支持。

自 1.5.0

degrees

degrees(expr) - 将弧度转换为度。

参数

expr - 弧度角

示例

> SELECT degrees(3.141592653589793);
 180.0

自 1.4.0

dense_rank

dense_rank() - 计算一组值中值的排名。结果是先前分配的排名值加一。与rank函数不同，dense_rank不会在排名序列中产生空隙。

参数

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的）索引处的元素。如果索引为0，Spark将抛出错误。如果索引小于0，则从后向前访问元素。如果索引超出数组长度且spark.sql.ansi.enabled设置为false，则函数返回NULL。如果spark.sql.ansi.enabled设置为true，则对于无效索引抛出ArrayIndexOutOfBoundsException。

element_at(map, key) - 返回给定键的值。如果map中不包含该键，则函数返回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。如果索引超出数组长度且spark.sql.ansi.enabled设置为false，则函数返回NULL。如果spark.sql.ansi.enabled设置为true，则对于无效索引抛出ArrayIndexOutOfBoundsException。

示例

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

自 2.0.0

encode

encode(str, charset) - 使用第二个参数字符集对第一个参数进行编码。如果任一参数为null，结果也将为null。

参数

str - 字符串表达式
charset - 'US-ASCII', 'ISO-8859-1', 'UTF-8', 'UTF-16BE', 'UTF-16LE', 'UTF-16', 'UTF-32'中的一个字符集，用于将str编码为BINARY。它不区分大小写。

示例

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

自 1.5.0

endswith

endswith(left, right) - 返回一个布尔值。如果left以right结尾，则值为True。如果任一输入表达式为NULL，则返回NULL。否则返回False。left和right都必须是STRING或BINARY类型。

示例

> 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) - 对于非空操作数，返回与EQUAL(=)运算符相同的结果，但如果两者都为null则返回true，如果其中一个为null则返回false。

参数

expr1, expr2 - 这两个表达式必须是相同类型或可以强制转换为公共类型，并且必须是可用于相等比较的类型。不支持Map类型。对于array/struct等复杂类型，字段的数据类型必须是可排序的。

示例

> 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的元素分离为多行，或将map expr的元素分离为多行和多列。除非另有指定，否则数组元素使用默认列名col，map元素使用key和value。

示例

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

自 1.0.0

explode_outer

explode_outer(expr) - 将数组expr的元素分离为多行，或将map expr的元素分离为多行和多列。除非另有指定，否则数组元素使用默认列名col，map元素使用key和value。

示例

> SELECT explode_outer(array(10, 20));
 10
 20
> SELECT 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周编号系统中，一月初的日期可能属于前一年的第52或53周，而十二月末的日期可能属于下一年的第一周。例如，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") - 秒字段，包括小数部分
- 间隔（由months、days、microseconds组成）的field支持的字符串值（不区分大小写）有
  - "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)在逗号分隔列表(str_array)中的索引（基于1）。如果未找到字符串或给定字符串(str)包含逗号，则返回0。

示例

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

自 1.5.0

first

first(expr[, isIgnoreNull]) - 返回一组行中expr的第一个值。如果isIgnoreNull为true，则只返回非空值。

示例

> 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，则只返回非空值。

示例

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

from_avro(child, jsonFormatSchema, options) - 将二进制Avro值转换为Catalyst值。

示例

> SELECT from_avro(s, '{"type": "record", "name": "struct", "fields": [{ "name": "u", "type": ["int","string"] }]}', map()) IS NULL AS result FROM (SELECT NAMED_STRUCT('u', NAMED_STRUCT('member0', member0, 'member1', member1)) AS s FROM VALUES (1, NULL), (NULL,  'a') tab(member0, member1));
 [false]

注意

指定的Schema必须与读取数据的实际Schema匹配，否则行为未定义：可能会失败或返回任意结果。要使用兼容和演进的Schema反序列化数据，可以通过相应的选项设置预期的Avro Schema。

自 4.0.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_protobuf

from_protobuf(data, messageName, descFilePath, options) - 将二进制Protobuf值转换为Catalyst值。

示例

> SELECT from_protobuf(s, 'Person', '/path/to/descriptor.desc', map()) IS NULL AS result FROM (SELECT NAMED_STRUCT('name', name, 'id', id) AS s FROM VALUES ('John Doe', 1), (NULL,  2) tab(name, id));
 [false]

注意

指定的Protobuf Schema必须与读取数据的实际Schema匹配，否则行为未定义：可能会失败或返回任意结果。要使用兼容和演进的Schema反序列化数据，可以通过相应的选项设置预期的Protobuf Schema。

自 4.0.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

from_xml

from_xml(xmlStr, schema[, options]) - 返回包含给定xmlStr和schema的结构体值。

示例

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

自 4.0.0

get

get(array, index) - 返回数组中给定（基于0的）索引处的元素。如果索引指向数组边界之外，则此函数返回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）。位置从右到左编号，从零开始。位置参数不能为负数。

示例

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

自 3.2.0

greatest

greatest(expr, ...) - 返回所有参数中的最大值，跳过空值。

示例

> 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的对数（以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(expr1的平方 + expr2的平方)。

示例

> 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不区分大小写地匹配带有escape的pattern，则返回true；如果任何参数为null，则返回null；否则返回false。

参数

str - 字符串表达式
pattern - 字符串表达式。该模式是一个字符串，按字面值且不区分大小写地匹配，但以下特殊符号除外

_ 匹配输入中的任意一个字符（类似于posix正则表达式中的.）

% 匹配输入中的零个或多个字符（类似于posix正则表达式中的.*）

自Spark 2.0起，字符串字面量在我们的SQL解析器中不再转义，请参阅字符串字面量中的转义规则。例如，要匹配"\abc"，模式应为"\abc"。

当SQL配置'spark.sql.parser.escapedStringLiterals'启用时，它会回退到Spark 1.6关于字符串字面量解析的行为。例如，如果该配置启用，匹配"\abc"的模式应为"\abc"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。
escape - 自Spark 3.0起添加的字符。默认的转义字符是'\'。如果转义字符位于特殊符号或另一个转义字符之前，则后面的字符将按字面值匹配。转义任何其他字符都是无效的。

示例

> SELECT ilike('Spark', '_Park');
true
> SELECT '\\abc' AS S, S ilike r'\\abc', S ilike '\\\\abc';
\abc    true    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 r'%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 * FROM inline(array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b
> SELECT * FROM inline(input => array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b

自 3.4.0

inline_outer

inline_outer(expr) - 将结构体数组展开为表。除非另有指定，否则默认使用列名col1、col2等。

示例

> SELECT * FROM inline_outer(array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b
> SELECT * FROM inline_outer(input => array(struct(1, 'a'), struct(2, 'b')));
 1  a
 2  b

自 3.4.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

is_valid_utf8

is_valid_utf8(str) - 如果str是有效的UTF-8字符串，则返回true，否则返回false。

参数

str - 字符串表达式

示例

> SELECT is_valid_utf8('Spark');
 true
> SELECT is_valid_utf8(x'61');
 true
> SELECT is_valid_utf8(x'80');
 false
> SELECT is_valid_utf8(x'61C262');
 false

自 4.0.0

is_variant_null

is_variant_null(expr) - 检查变体值是否为变体null。当且仅当输入为变体null时返回true，否则返回false（包括SQL NULL的情况）。

示例

> SELECT is_variant_null(parse_json('null'));
 true
> SELECT is_variant_null(parse_json('"null"'));
 false
> SELECT is_variant_null(parse_json('13'));
 false
> SELECT is_variant_null(parse_json(null));
 false
> SELECT is_variant_null(variant_get(parse_json('{"a":null, "b":"spark"}'), "$.c"));
 false
> SELECT is_variant_null(variant_get(parse_json('{"a":null, "b":"spark"}'), "$.a"));
 true

自 4.0.0

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，则只返回非空值。

示例

> 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，则只返回非空值。

示例

> 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, ...) - 返回所有参数中的最小值，跳过空值。

示例

> 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距离。如果设置了阈值且距离超过该阈值，则返回-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 - 字符串表达式。该模式是一个字符串，按字面值匹配，但以下特殊符号除外

_ 匹配输入中的任意一个字符（类似于posix正则表达式中的.）\ % 匹配输入中的零个或多个字符（类似于posix正则表达式中的.*）

自Spark 2.0起，字符串字面量在我们的SQL解析器中不再转义，请参阅字符串字面量中的转义规则。例如，要匹配"\abc"，模式应为"\abc"。

当SQL配置'spark.sql.parser.escapedStringLiterals'启用时，它会回退到Spark 1.6关于字符串字面量解析的行为。例如，如果该配置启用，匹配"\abc"的模式应为"\abc"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。
escape - 自Spark 3.0起添加的字符。默认的转义字符是'\'。如果转义字符位于特殊符号或另一个转义字符之前，则后面的字符将按字面值匹配。转义任何其他字符都是无效的。

示例

> SELECT like('Spark', '_park');
true
> SELECT '\\abc' AS S, S like r'\\abc', S like '\\\\abc';
\abc    true    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 r'%SystemDrive%\\Users%';
true
> SELECT '%SystemDrive%/Users/John' like '/%SystemDrive/%//Users%' ESCAPE '/';
true

注意

使用RLIKE与标准正则表达式匹配。

自 1.0.0

listagg

listagg(expr[, delimiter])[ WITHIN GROUP (ORDER BY key [ASC | DESC] [,...])] - 返回非NULL输入值的连接，按键排序并由分隔符分隔。如果所有值都为NULL，则返回NULL。

参数

expr - 要连接的字符串或二进制表达式。
delimiter - 可选的字符串或二进制可折叠表达式，用于分隔输入值。如果为NULL，则连接将不带分隔符执行。默认值为NULL。
key - 用于对输入值进行排序的可选表达式。可以指定多个键。如果没有指定，则结果中行的顺序是非确定性的。

示例

> SELECT listagg(col) FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 abc
> SELECT listagg(col) WITHIN GROUP (ORDER BY col DESC) FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 cba
> SELECT listagg(col) FROM VALUES ('a'), (NULL), ('b') AS tab(col);
 ab
> SELECT listagg(col) FROM VALUES ('a'), ('a') AS tab(col);
 aa
> SELECT listagg(DISTINCT col) FROM VALUES ('a'), ('a'), ('b') AS tab(col);
 ab
> SELECT listagg(col, ', ') FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 a, b, c
> SELECT listagg(col) FROM VALUES (NULL), (NULL) AS tab(col);
 NULL

注意

如果未指定顺序，则该函数是非确定性的，因为混洗后行的顺序可能是不确定性的。
如果指定了DISTINCT，则expr和key必须是相同的表达式。

自 4.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) - 返回以base为底expr的对数。

示例

> SELECT log(10, 100);
 2.0

自 1.5.0

log10

log10(expr) - 返回以10为底expr的对数。

示例

> 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) - 返回以2为底expr的对数。

示例

> 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(year, month, day) - 从年、月、日字段创建日期。如果配置spark.sql.ansi.enabled为false，则函数在无效输入时返回NULL。否则，它将抛出错误。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从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([days[, hours[, mins[, secs]]]]) - 从天、小时、分钟和秒创建DayTimeIntervalType持续时间。

参数

days - 天数，正数或负数
hours - 小时数，正数或负数
mins - 分钟数，正数或负数
secs - 秒数，带微秒精度的小数部分。

示例

> 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([years[, months[, weeks[, days[, hours[, mins[, secs]]]]]]]) - 从年、月、周、日、小时、分钟和秒创建间隔。

参数

years - 年数，正数或负数
months - 月数，正数或负数
weeks - 周数，正数或负数
days - 天数，正数或负数
hours - 小时数，正数或负数
mins - 分钟数，正数或负数
secs - 秒数，带微秒精度的小数部分。

示例

> 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(year, month, day, hour, min, sec[, timezone]) - 从年、月、日、小时、分钟、秒和时区字段创建时间戳。结果数据类型与配置spark.sql.timestampType的值一致。如果配置spark.sql.ansi.enabled为false，则函数在无效输入时返回NULL。否则，它将抛出错误。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从0到60。该值可以是整数，如13，也可以是小数，如13.123。如果sec参数等于60，则秒字段设置为0，并在最终时间戳中增加1分钟。
timezone - 时区标识符。例如，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(year, month, day, hour, min, sec[, timezone]) - 从年、月、日、小时、分钟、秒和时区字段创建带本地时区的当前时间戳。如果配置spark.sql.ansi.enabled为false，则函数在无效输入时返回NULL。否则，它将抛出错误。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从0到60。如果sec参数等于60，则秒字段设置为0，并在最终时间戳中增加1分钟。
timezone - 时区标识符。例如，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(year, month, day, hour, min, sec) - 从年、月、日、小时、分钟、秒字段创建本地日期时间。如果配置spark.sql.ansi.enabled为false，则函数在无效输入时返回NULL。否则，它将抛出错误。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从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_valid_utf8

make_valid_utf8(str) - 如果str是有效的UTF-8字符串，则返回原始字符串，否则返回一个新字符串，其中无效的UTF8字节序列将使用UNICODE替换字符U+FFFD替换。

参数

str - 字符串表达式

示例

> SELECT make_valid_utf8('Spark');
 Spark
> SELECT make_valid_utf8(x'61');
 a
> SELECT make_valid_utf8(x'80');
 �
> SELECT make_valid_utf8(x'61C262');
 a�b

自 4.0.0

make_ym_interval

make_ym_interval([years[, months]]) - 从年、月创建年月间隔。

参数

years - 年数，正数或负数
months - 月数，正数或负数

示例

> 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, ...) - 使用给定的键/值对创建映射。

示例

> 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) - 如果映射包含该键，则返回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) - 使用给定键/值数组对创建映射。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) - 返回包含映射键的无序数组。

示例

> 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) - 通过将函数应用于具有相同键的值对，将两个给定映射合并为一个映射。对于仅存在于一个映射中的键，将传入NULL作为缺失键的值。如果输入映射包含重复键，则只有重复键的第一个条目会传递给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 - 要掩码的字符串值。支持的类型：STRING、VARCHAR、CHAR
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

注意

该函数是非确定性的，因此对于与x具有相同值关联的输出，顺序可能不同。

自 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

注意

该函数是非确定性的，因此对于与x具有相同值关联的输出，顺序可能不同。

自 3.0.0

minute

minute(时间戳) - 返回字符串/时间戳的分钟部分。

示例

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

自 1.5.0

mod

expr1 % expr2, 或 mod(expr1, expr2) - 返回expr1/expr2后的余数。

示例

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

自 2.3.0

mode

mode(列[, 确定性]) - 返回列中出现频率最高的值。NULL 值将被忽略。如果所有值均为 NULL，或行数为 0，则返回 NULL。当多个值具有相同的最高频率时，如果确定性为 false 或未定义，则返回其中任意一个值；如果确定性为 true，则返回最低值。mode() WITHIN GROUP (ORDER BY 列) - 返回列中出现频率最高的值（在 ORDER BY 子句中指定）。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
> SELECT mode(col, false) FROM VALUES (-10), (0), (10) AS tab(col);
 0
> SELECT mode(col, true) FROM VALUES (-10), (0), (10) AS tab(col);
 -10
> SELECT mode() WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10), (10) AS tab(col);
 10
> SELECT mode() WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10), (10), (20), (20) AS tab(col);
 10
> SELECT mode() WITHIN GROUP (ORDER BY col DESC) FROM VALUES (0), (10), (10), (20), (20) AS tab(col);
 20

自 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(日期) - 返回日期/时间戳的月份部分。

示例

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

自 1.5.0

monthname

monthname(日期) - 返回给定日期的月份三字母缩写名称。

示例

> SELECT monthname('2008-02-20');
 Feb

自 4.0.0

months_between

months_between(时间戳1, 时间戳2[, roundOff]) - 如果时间戳1晚于时间戳2，则结果为正数。如果时间戳1和时间戳2在同一个月的同一天，或都为月末最后一天，则忽略当天时间。否则，差值将基于每月 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(名称1, 值1, 名称2, 值2, ...) - 使用给定的字段名称和值创建结构体。

示例

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

自 1.5.0

nanvl

nanvl(表达式1, 表达式2) - 如果表达式1不是 NaN，则返回表达式1；否则返回表达式2。

示例

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

自 1.5.0

negative

negative(表达式) - 返回表达式的负值。

示例

> SELECT negative(1);
 -1

自 1.0.0

next_day

next_day(开始日期, 星期几) - 返回晚于开始日期且指定名称的第一个日期。如果至少一个输入参数为 NULL，则函数返回 NULL。当两个输入参数都不为 NULL 且星期几为无效输入时，如果 spark.sql.ansi.enabled 设置为 true，则函数抛出 SparkIllegalArgumentException；否则返回 NULL。

示例

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

自 1.5.0

not

not 表达式 - 逻辑非。

示例

> 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(输入[, 偏移量]) - 返回窗口帧开头第“偏移量”行的输入值。偏移量从 1 开始。如果 ignoreNulls=true，则在查找第“偏移量”行时跳过空值。否则，每行都计入偏移量。如果不存在这样的第“偏移量”行（例如，当偏移量为 10，而窗口帧大小小于 10 时），则返回空值。

参数

输入 - 函数操作的目标列或表达式。
偏移量 - 一个正整数文字，表示窗口帧中的偏移量。它从 1 开始。
ignoreNulls - 一个可选规范，指示 NthValue 在确定使用哪一行时应跳过空值。

示例

> 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) - 将每个窗口分区中的行分为 n 个桶，范围从 1 到最多 n。

参数

桶 - 一个整数表达式，表示要将行分割成的桶的数量。默认值为 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(表达式1, 表达式2) - 如果表达式1等于表达式2，则返回 null；否则返回表达式1。

示例

> SELECT nullif(2, 2);
 NULL

自 2.0.0

nullifzero

nullifzero(表达式) - 如果表达式等于零，则返回 null；否则返回表达式。

示例

> SELECT nullifzero(0);
 NULL
> SELECT nullifzero(2);
 2

自 4.0.0

nvl

nvl(表达式1, 表达式2) - 如果表达式1为 null，则返回表达式2；否则返回表达式1。

示例

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

自 2.0.0

nvl2

nvl2(表达式1, 表达式2, 表达式3) - 如果表达式1不为 null，则返回表达式2；否则返回表达式3。

示例

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

自 2.0.0

octet_length

octet_length(表达式) - 返回字符串数据的字节长度或二进制数据的字节数。

示例

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

自 2.3.0

or

表达式1 or 表达式2 - 逻辑或。

示例

> 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(输入, 替换, 位置[, 长度]) - 用从位置开始，长度为长度的替换字符串替换输入。

示例

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

parse_json(json字符串) - 将 JSON 字符串解析为 Variant 值。当字符串不是有效的 JSON 值时抛出异常。

示例

> SELECT parse_json('{"a":1,"b":0.8}');
 {"a":1,"b":0.8}

自 4.0.0

parse_url

parse_url(URL, 要提取的部分[, 键]) - 从 URL 中提取一部分。

示例

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

自 2.0.0

percent_rank

percent_rank() - 计算一组值中某个值的百分比排名。

参数

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(列, 百分比[, 频率]) - 返回给定百分比下数值或 ANSI 区间列 col 的精确百分位数。百分比的值必须在 0.0 到 1.0 之间。频率的值应为正整数。

percentile(列, 数组(百分比1[, 百分比2]...) [, 频率]) - 返回给定百分比（一个或多个）下数值列 col 的精确百分位数数组。百分比数组的每个值都必须在 0.0 到 1.0 之间。频率的值应为正整数。

示例

> 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(列, 百分比[, 精度]) - 返回数值或 ANSI 区间列 col 的近似百分位数，它是已排序的 col 值（从小到大排序）中的最小值，使得不超过百分比的 col 值小于或等于该值。百分比的值必须在 0.0 到 1.0 之间。accuracy 参数（默认值：10000）是一个正数值字面量，它以内存为代价控制近似精度。精度值越高，精度越好，1.0/accuracy 是近似值的相对误差。当百分比是一个数组时，百分比数组的每个值都必须在 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

percentile_cont

percentile_cont(百分比) WITHIN GROUP (ORDER BY 列) - 根据数值或 ANSI 区间列 col 的连续分布，在给定百分比（在 ORDER BY 子句中指定）处返回百分位数。

示例

> SELECT percentile_cont(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10) AS tab(col);
 2.5
> SELECT percentile_cont(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-2

自 4.0.0

percentile_disc

percentile_disc(百分比) WITHIN GROUP (ORDER BY 列) - 根据数值或 ANSI 区间列 col 的离散分布，在给定百分比（在 ORDER BY 子句中指定）处返回百分位数。

示例

> SELECT percentile_disc(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10) AS tab(col);
 0.0
> SELECT percentile_disc(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (INTERVAL '0' MONTH), (INTERVAL '10' MONTH) AS tab(col);
 0-0

自 4.0.0

pi

pi() - 返回 pi。

示例

> SELECT pi();
 3.141592653589793

自 1.5.0

pmod

pmod(表达式1, 表达式2) - 返回表达式1对表达式2取模后的正值。

示例

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

自 1.5.0

posexplode

posexplode(表达式) - 将数组表达式的元素拆分为多行并带位置，或将映射表达式的元素拆分为多行多列并带位置。除非另有指定，否则位置使用列名 pos，数组元素使用 col，或映射元素使用 key 和 value。

示例

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

自 3.5.0

posexplode_outer

posexplode_outer(表达式) - 将数组表达式的元素拆分为多行并带位置，或将映射表达式的元素拆分为多行多列并带位置。除非另有指定，否则位置使用列名 pos，数组元素使用 col，或映射元素使用 key 和 value。

示例

> SELECT posexplode_outer(array(10,20));
 0  10
 1  20
> SELECT posexplode_outer(collection => array(10,20));
 0  10
 1  20

自 2.0.0

position

position(子字符串, 字符串[, 位置]) - 返回子字符串在字符串中，从给定位置之后第一次出现的位置。给定的位置和返回值都是基于 1 的。

示例

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

自 2.3.0

positive

positive(表达式) - 返回表达式的值。

示例

> SELECT positive(1);
 1

自 1.5.0

pow

pow(表达式1, 表达式2) - 将表达式1提升到表达式2的幂次。

示例

> SELECT pow(2, 3);
 8.0

自 1.4.0

power

power(表达式1, 表达式2) - 将表达式1提升到表达式2的幂次。

示例

> SELECT power(2, 3);
 8.0

自 1.4.0

printf

printf(格式字符串, 对象, ...) - 从 printf 样式的格式字符串返回一个格式化字符串。

示例

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

自 1.5.0

quarter

quarter(日期) - 返回日期的年份季度，范围在 1 到 4 之间。

示例

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

自 1.5.0

radians

radians(表达式) - 将度转换为弧度。

参数

表达式 - 以度为单位的角度

示例

> SELECT radians(180);
 3.141592653589793

自 1.4.0

raise_error

raise_error( 表达式 ) - 抛出 USER_RAISED_EXCEPTION，表达式作为消息。

示例

> SELECT raise_error('custom error message');
 [USER_RAISED_EXCEPTION] custom error message

自 3.1.0

rand

rand([种子]) - 返回一个随机值，该值具有独立同分布 (i.i.d.) 的 [0, 1) 区间内的均匀分布值。

示例

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

注意

在一般情况下，该函数是非确定性的。

自 1.5.0

randn

randn([种子]) - 返回一个随机值，该值具有独立同分布 (i.i.d.) 的标准正态分布值。

示例

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

注意

在一般情况下，该函数是非确定性的。

自 1.5.0

random

random([种子]) - 返回一个随机值，该值具有独立同分布 (i.i.d.) 的 [0, 1) 区间内的均匀分布值。

示例

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

注意

在一般情况下，该函数是非确定性的。

自 3.0.0

randstr

randstr(长度[, 种子]) - 返回一个指定长度的字符串，其字符是从以下字符池中均匀随机选择的：0-9、a-z、A-Z。随机种子是可选的。字符串长度必须是常量两字节或四字节整数（分别为 SMALLINT 或 INT）。

示例

> SELECT randstr(3, 0) AS result;
 ceV

自 4.0.0

range

range(开始[, 结束[, 步长[, 分区数]]]) / range(结束) - 返回指定范围内的一系列值的表。

参数

开始 - 一个可选的 BIGINT 字面量，默认值为 0，标记生成的第一个值。
结束 - 一个 BIGINT 字面量，标记数字生成的结束点（不包含）。
步长 - 一个可选的 BIGINT 字面量，默认值为 1，指定生成值时使用的增量。
分区数 - 一个可选的 INTEGER 字面量，指定行在分区中的分布方式。

示例

> SELECT * FROM range(1);
  +---+
  | id|
  +---+
  |  0|
  +---+
> SELECT * FROM range(0, 2);
  +---+
  |id |
  +---+
  |0  |
  |1  |
  +---+
> SELECT * FROM range(0, 4, 2);
  +---+
  |id |
  +---+
  |0  |
  |2  |
  +---+

自 2.0.0

rank

rank() - 计算一组值中某个值的排名。结果是当前行在分区排序中之前或等于当前行的行数加一。这些值将在序列中产生空隙。

参数

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(表达式, 初始状态, 合并, 完成) - 对初始状态和数组中的所有元素应用一个二元运算符，并将其归约为单一状态。通过应用一个完成函数，最终状态被转换为最终结果。

示例

> 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(类, 方法[, 参数1[, 参数2 ..]]) - 使用反射调用方法。

示例

> 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(字符串, 正则表达式) - 如果字符串匹配正则表达式，则返回 true；否则返回 false。

参数

str - 字符串表达式
正则表达式 - 一个字符串表达式。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。

示例

> 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
> SELECT regexp('%SystemDrive%\\Users\\John', r'%SystemDrive%\\Users.*');
true

注意

使用 LIKE 匹配简单的字符串模式。

自 3.2.0

regexp_count

regexp_count(字符串, 正则表达式) - 返回正则表达式模式 regexp 在字符串 str 中匹配的次数。

参数

字符串 - 一个字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 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(字符串, 正则表达式[, 索引]) - 提取字符串中与正则表达式 regexp 匹配的第一个字符串，并对应于正则表达式组索引。

参数

字符串 - 一个字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。
索引 - 表示组索引的整数表达式。正则表达式可能包含多个组。idx 指示要提取哪个正则表达式组。组索引应为非负数。idx 的最小值为 0，表示匹配整个正则表达式。如果 idx 未指定，则默认组索引值为 1。idx 参数是 Java 正则表达式 Matcher group() 方法的索引。

示例

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

自 1.5.0

regexp_extract_all

regexp_extract_all(字符串, 正则表达式[, 索引]) - 提取字符串中所有与正则表达式 regexp 匹配的字符串，并对应于正则表达式组索引。

参数

字符串 - 一个字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。
索引 - 表示组索引的整数表达式。正则表达式可能包含多个组。idx 指示要提取哪个正则表达式组。组索引应为非负数。idx 的最小值为 0，表示匹配整个正则表达式。如果 idx 未指定，则默认组索引值为 1。idx 参数是 Java 正则表达式 Matcher group() 方法的索引。

示例

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

自 3.1.0

regexp_instr

regexp_instr(字符串, 正则表达式) - 在字符串中搜索正则表达式，并返回一个整数，指示匹配子字符串的起始位置。位置是基于 1 的，而不是基于 0 的。如果没有找到匹配项，则返回 0。

参数

字符串 - 一个字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。

示例

> SELECT regexp_instr(r"\abc", r"^\\abc$");
 1
> SELECT regexp_instr('user@spark.apache.org', '@[^.]*');
 5

自 3.4.0

regexp_like

regexp_like(字符串, 正则表达式) - 如果字符串匹配正则表达式，则返回 true；否则返回 false。

参数

str - 字符串表达式
正则表达式 - 一个字符串表达式。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。

示例

> 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
> SELECT regexp_like('%SystemDrive%\\Users\\John', r'%SystemDrive%\\Users.*');
true

注意

使用 LIKE 匹配简单的字符串模式。

自 3.2.0

regexp_replace

regexp_replace(字符串, 正则表达式, 替换字符串[, 位置]) - 将字符串中所有匹配正则表达式 regexp 的子字符串替换为 rep。

参数

字符串 - 用于搜索正则表达式模式匹配的字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。
替换字符串 - 用于替换匹配子字符串的字符串表达式。
位置 - 一个正整数文字，指示在字符串中开始搜索的位置。默认值为 1。如果位置大于字符串中的字符数，则结果为字符串本身。

示例

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

自 1.5.0

regexp_substr

regexp_substr(字符串, 正则表达式) - 返回字符串中与正则表达式 regexp 匹配的子字符串。如果未找到正则表达式，则结果为 null。

参数

字符串 - 一个字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 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, null) AS tab(y, x);
 0
> SELECT regr_count(y, x) FROM VALUES (null, 1) AS tab(y, x);
 0
> 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), (4, 4) 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
> SELECT regr_intercept(y, x) FROM VALUES (1, 1), (2, null), (3, 3), (4, 4) AS tab(y, x);
 0.0
> SELECT regr_intercept(y, x) FROM VALUES (1, 1), (2, null), (null, 3), (4, 4) AS tab(y, x);
 0.0

自 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), (4, 4) 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
> SELECT regr_slope(y, x) FROM VALUES (1, 1), (2, null), (3, 3), (4, 4) AS tab(y, x);
 1.0
> SELECT regr_slope(y, x) FROM VALUES (1, 1), (2, null), (null, 3), (4, 4) AS tab(y, x);
 1.0

自 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, null) AS tab(y, x);
 NULL
> SELECT regr_sxx(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> 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, null) AS tab(y, x);
 NULL
> SELECT regr_sxy(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> 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, null) AS tab(y, x);
 NULL
> SELECT regr_syy(y, x) FROM VALUES (null, 1) AS tab(y, x);
 NULL
> 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(字符串, n) - 返回重复给定字符串值 n 次的字符串。

示例

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

自 1.5.0

replace

replace(字符串, 搜索字符串[, 替换字符串]) - 将所有出现的 search 替换为 replace。

参数

str - 字符串表达式
搜索字符串 - 一个字符串表达式。如果在字符串中未找到 search，则返回未更改的字符串。
替换字符串 - 一个字符串表达式。如果未指定 replace 或替换字符串为空，则不替换从字符串中移除的部分。

示例

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

自 2.3.0

reverse

reverse(数组) - 返回反转的字符串或元素顺序反转的数组。

示例

> 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（len 可以是字符串类型）个字符，如果 len 小于或等于 0，则结果为空字符串。

示例

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

自 2.3.0

rint

rint(表达式) - 返回最接近参数值且等于数学整数的双精度值。

示例

> SELECT rint(12.3456);
 12.0

自 1.4.0

rlike

rlike(字符串, 正则表达式) - 如果字符串匹配正则表达式，则返回 true；否则返回 false。

参数

str - 字符串表达式
正则表达式 - 一个字符串表达式。正则表达式字符串应为 Java 正则表达式。

自 Spark 2.0 起，我们的 SQL 解析器中字符串字面量（包括正则表达式模式）不再转义，请参阅字符串字面量处的非转义规则。例如，要匹配 "\abc"，正则表达式可以是 "^\abc$"。

有一个 SQL 配置 'spark.sql.parser.escapedStringLiterals' 可用于回退到 Spark 1.6 中字符串字面量解析的行为。例如，如果该配置已启用，则可以匹配 "\abc" 的正则表达式是 "^\abc$"。

建议使用原始字符串字面量（带有r前缀）来避免模式字符串中存在的特殊字符转义。

示例

> 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
> SELECT rlike('%SystemDrive%\\Users\\John', r'%SystemDrive%\\Users.*');
true

注意

使用 LIKE 匹配简单的字符串模式。

自 1.0.0

round

round(表达式, d) - 使用 HALF_UP 舍入模式将表达式四舍五入到 d 位小数。

示例

> SELECT round(2.5, 0);
 3

自 1.5.0

row_number

row_number() - 根据窗口分区内行的排序，为每行分配一个从一开始的唯一序列号。

示例

> 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，右侧用 pad 填充到长度 len。如果 str 长于 len，则返回值将缩短为 len 字符。如果未指定 pad，则如果字符串是字符字符串，将用空格字符在右侧填充；如果是二进制字符串，则用零填充。

示例

> 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 - 字符串表达式
trimStr - 要修剪的字符串字符，默认值为单个空格

示例

> SELECT rtrim('    SparkSQL   ');
 SparkSQL

自 1.5.0

schema_of_avro

schema_of_avro(JSON格式AvroSchema, 选项) - 以 DDL 格式返回 JSON 字符串格式的 Avro 模式。

示例

> SELECT schema_of_avro('{"type": "record", "name": "struct", "fields": [{"name": "u", "type": ["int", "string"]}]}', map());
 STRUCT<u: STRUCT<member0: INT, member1: STRING> NOT NULL>

自 4.0.0

schema_of_csv

schema_of_csv(CSV字符串[, 选项]) - 以 DDL 格式返回 CSV 字符串的模式。

示例

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

自 3.0.0

schema_of_json

schema_of_json(JSON字符串[, 选项]) - 以 DDL 格式返回 JSON 字符串的模式。

示例

> 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

schema_of_variant

schema_of_variant(变体) - 以 SQL 格式返回变体的模式。

示例

> SELECT schema_of_variant(parse_json('null'));
 VOID
> SELECT schema_of_variant(parse_json('[{"b":true,"a":0}]'));
 ARRAY<OBJECT<a: BIGINT, b: BOOLEAN>>

自 4.0.0

schema_of_variant_agg

schema_of_variant_agg(变体) - 以 SQL 格式返回变体列的合并模式。

示例

> SELECT schema_of_variant_agg(parse_json(j)) FROM VALUES ('1'), ('2'), ('3') AS tab(j);
 BIGINT
> SELECT schema_of_variant_agg(parse_json(j)) FROM VALUES ('{"a": 1}'), ('{"b": true}'), ('{"c": 1.23}') AS tab(j);
 OBJECT<a: BIGINT, b: BOOLEAN, c: DECIMAL(3,2)>

自 4.0.0

schema_of_xml

schema_of_xml(XML字符串[, 选项]) - 以 DDL 格式返回 XML 字符串的模式。

示例

> SELECT schema_of_xml('<p><a>1</a></p>');
 STRUCT<a: BIGINT>
> SELECT schema_of_xml('<p><a attr="2">1</a><a>3</a></p>', map('excludeAttribute', 'true'));
 STRUCT<a: ARRAY<BIGINT>>

自 4.0.0

sec

sec(表达式) - 返回表达式的割线，如同由 1/java.lang.Math.cos 计算。

参数

expr - 弧度角

示例

> SELECT sec(0);
 1.0

自 3.3.0

second

second(时间戳) - 返回字符串/时间戳的秒部分。

示例

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

自 1.5.0

sentences

sentences(字符串[, 语言[, 国家]]) - 将字符串拆分为词语数组的数组。

参数

字符串 - 要解析的 STRING 表达式。
语言 - 一个可选的 STRING 表达式，包含来自 ISO 639 Alpha-2（例如 'DE'）、Alpha-3 的语言代码，或最多 8 个字符的语言子标签。
国家 - 一个可选的 STRING 表达式，包含来自 ISO 3166 alpha-2 国家代码或 UN M.49 数字-3 区域代码的国家代码。

示例

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

自 2.0.0

sequence

sequence(开始, 停止, 步长) - 生成一个从开始到停止（包含）的元素数组，按步长递增。返回元素的类型与参数表达式的类型相同。

支持的类型有：byte、short、integer、long、date、timestamp。

开始和停止表达式必须解析为相同的类型。如果开始和停止表达式解析为“date”或“timestamp”类型，则步长表达式必须解析为“interval”或“year-month interval”或“day-time interval”类型；否则，应与开始和停止表达式的类型相同。

参数

开始 - 一个表达式。范围的开始。
停止 - 一个表达式。范围的结束（包含）。
步长 - 一个可选表达式。范围的步长。默认情况下，如果开始小于或等于停止，步长为 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_user

session_user() - 当前执行上下文的用户名。

示例

> SELECT session_user();
 mockingjay

自 4.0.0

session_window

session_window(时间列, 间隔持续时间) - 给定时间戳指定列和间隔持续时间，生成会话窗口。有关详细说明和示例，请参阅结构化流指南文档中的“时间窗口类型”。

参数

时间列 - 用作按时间分窗的时间戳的列或表达式。时间列必须是 TimestampType 类型。
间隔持续时间 - 一个字符串，指定会话的超时时间，表示为“间隔值”（有关详细信息，请参阅间隔字面量），用于固定间隔持续时间；或者是一个对每个输入应用并计算为“间隔值”的表达式，用于动态间隔持续时间。

示例

> 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(表达式) - 返回表达式的 sha1 哈希值作为十六进制字符串。

示例

> SELECT sha('Spark');
 85f5955f4b27a9a4c2aab6ffe5d7189fc298b92c

自 1.5.0

sha1

sha1(表达式) - 返回表达式的 sha1 哈希值作为十六进制字符串。

示例

> SELECT sha1('Spark');
 85f5955f4b27a9a4c2aab6ffe5d7189fc298b92c

自 1.5.0

sha2

sha2(表达式, 位长度) - 返回表达式的 SHA-2 系列校验和作为十六进制字符串。支持 SHA-224、SHA-256、SHA-384 和 SHA-512。位长度为 0 等同于 256。

示例

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

自 1.5.0

shiftleft

基数左移表达式 - 按位左移。

示例

> SELECT shiftleft(2, 1);
 4
> SELECT 2 << 1;
 4

注意

<< 运算符在 Spark 4.0.0 中作为 shiftleft 的别名添加。

自 1.5.0

shiftright

基数右移表达式 - 按位（有符号）右移。

示例

> SELECT shiftright(4, 1);
 2
> SELECT 4 >> 1;
 2

注意

>> 运算符在 Spark 4.0.0 中作为 shiftright 的别名添加。

自 1.5.0

shiftrightunsigned

基数无符号右移表达式 - 按位无符号右移。

示例

> SELECT shiftrightunsigned(4, 1);
 2
> SELECT 4 >>> 1;
 2

注意

>>> 运算符在 Spark 4.0.0 中作为 shiftrightunsigned 的别名添加。

自 1.5.0

shuffle

shuffle(数组) - 返回给定数组的随机排列。

示例

> 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(表达式) - 如果表达式为负、0 或正，则分别返回 -1.0、0.0 或 1.0。

示例

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

自 1.4.0

signum

signum(表达式) - 如果表达式为负、0 或正，则分别返回 -1.0、0.0 或 1.0。

示例

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

自 1.4.0

sin

sin(表达式) - 返回表达式的正弦值，如同由 java.lang.Math.sin 计算。

参数

expr - 弧度角

示例

> SELECT sin(0);
 0.0

自 1.4.0

sinh

sinh(表达式) - 返回表达式的双曲正弦值，如同由 java.lang.Math.sinh 计算。

参数

expr - 双曲角

示例

> SELECT sinh(0);
 0.0

自 1.4.0

size

size(表达式) - 返回数组或映射的大小。仅当 spark.sql.ansi.enabled 为 false 且 spark.sql.legacy.sizeOfNull 为 true 时，此函数才对 null 输入返回 -1。否则，它对 null 输入返回 null。在默认设置下，该函数对 null 输入返回 null。

示例

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

自 1.5.0

skewness

skewness(表达式) - 返回从组值中计算出的偏度值。

示例

> 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, 开始, 长度) - 从索引开始（数组索引从 1 开始，如果开始为负则从末尾开始）截取数组 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(表达式) - 将表达式的值转换为目标数据类型 smallint。

自 2.0.1

some

some(表达式) - 如果表达式的至少一个值为 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(数组[, 升序]) - 根据数组元素的自然排序，按升序或降序对输入数组进行排序。对于 double/float 类型，NaN 大于任何非 NaN 元素。在升序排列时，空元素将放在返回数组的开头；在降序排列时，将放在返回数组的末尾。

示例

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

自 1.5.0

soundex

soundex(字符串) - 返回字符串的 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(字符串, 正则表达式, 限制) - 根据匹配正则表达式的出现次数拆分字符串，并返回一个长度最多为限制的数组。

参数

字符串 - 要拆分的字符串表达式。
正则表达式 - 表示正则表达式的字符串。正则表达式字符串应为 Java 正则表达式。
限制 - 一个整数表达式，控制正则表达式应用的次数。
- 限制 > 0: 结果数组的长度不会超过限制，并且结果数组的最后一个条目将包含所有超出最后一个匹配正则表达式的输入。
- 限制 <= 0: 正则表达式将尽可能多地应用，并且结果数组可以是任意大小。

示例

> 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(字符串, 分隔符, 部分编号) - 按分隔符拆分字符串，并返回拆分中请求的部分（基于 1）。如果任何输入为 null，则返回 null。如果部分编号超出拆分部分的范围，则返回空字符串。如果部分编号为 0，则抛出错误。如果部分编号为负数，则从字符串末尾向后计数部分。如果分隔符为空字符串，则不拆分字符串。

示例

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

自 3.3.0

sql_keywords

sql_keywords() - 获取 Spark SQL 关键字

示例

> SELECT * FROM sql_keywords() LIMIT 2;
 ADD  false
 AFTER  false

自 3.5.0

sqrt

sqrt(表达式) - 返回表达式的平方根。

示例

> SELECT sqrt(4);
 2.0

自 1.1.1

stack

stack(n, 表达式1, ..., 表达式k) - 将表达式1、...、表达式k 分成 n 行。默认使用列名 col0、col1 等，除非另有指定。

示例

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

自 2.0.0

startswith

startswith(左, 右) - 返回布尔值。如果左字符串以右字符串开头，则值为 True。如果任一输入表达式为 NULL，则返回 NULL。否则，返回 False。左字符串和右字符串都必须是 STRING 或 BINARY 类型。

示例

> 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(表达式) - 返回从组值中计算出的样本标准差。

示例

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

自 1.6.0

stddev

stddev(表达式) - 返回从组值中计算出的样本标准差。

示例

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

自 1.6.0

stddev_pop

stddev_pop(表达式) - 返回从组值中计算出的总体标准差。

示例

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

自 1.6.0

stddev_samp

stddev_samp(表达式) - 返回从组值中计算出的样本标准差。

示例

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

自 1.6.0

str_to_map

str_to_map(文本[, 对分隔符[, 键值分隔符]]) - 使用分隔符将文本拆分为键/值对后创建映射。默认分隔符是用于 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(表达式) - 将表达式的值转换为目标数据类型 string。

自 2.0.1

string_agg

string_agg(表达式[, 分隔符])[ WITHIN GROUP (ORDER BY 键 [ASC | DESC] [,...])] - 返回非 NULL 输入值的串联，按键排序并由分隔符分隔。如果所有值均为 NULL，则返回 NULL。

参数

expr - 要连接的字符串或二进制表达式。
delimiter - 可选的字符串或二进制可折叠表达式，用于分隔输入值。如果为NULL，则连接将不带分隔符执行。默认值为NULL。
key - 用于对输入值进行排序的可选表达式。可以指定多个键。如果没有指定，则结果中行的顺序是非确定性的。

示例

> SELECT string_agg(col) FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 abc
> SELECT string_agg(col) WITHIN GROUP (ORDER BY col DESC) FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 cba
> SELECT string_agg(col) FROM VALUES ('a'), (NULL), ('b') AS tab(col);
 ab
> SELECT string_agg(col) FROM VALUES ('a'), ('a') AS tab(col);
 aa
> SELECT string_agg(DISTINCT col) FROM VALUES ('a'), ('a'), ('b') AS tab(col);
 ab
> SELECT string_agg(col, ', ') FROM VALUES ('a'), ('b'), ('c') AS tab(col);
 a, b, c
> SELECT string_agg(col) FROM VALUES (NULL), (NULL) AS tab(col);
 NULL

注意

如果未指定顺序，则该函数是非确定性的，因为混洗后行的顺序可能是不确定性的。
如果指定了DISTINCT，则expr和key必须是相同的表达式。

自 4.0.0

struct

struct(列1, 列2, 列3, ...) - 使用给定的字段值创建结构体。

示例

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

自 1.4.0

substr

substr(字符串, 位置[, 长度]) - 返回从位置开始，长度为长度的字符串的子字符串，或从位置开始，长度为长度的字节数组切片。

substr(字符串 FROM 位置[ FOR 长度]]) - 返回从位置开始，长度为长度的字符串的子字符串，或从位置开始，长度为长度的字节数组切片。

示例

> 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(字符串, 位置[, 长度]) - 返回从位置开始，长度为长度的字符串的子字符串，或从位置开始，长度为长度的字节数组切片。

substring(字符串 FROM 位置[ FOR 长度]]) - 返回从位置开始，长度为长度的字符串的子字符串，或从位置开始，长度为长度的字节数组切片。

示例

> 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(字符串, 分隔符, 计数) - 返回字符串中在分隔符出现 count 次之前的部分。如果 count 为正，则返回最后一个分隔符（从左计数）左侧的所有内容。如果 count 为负，则返回最后一个分隔符（从右计数）右侧的所有内容。函数 substring_index 在搜索 delim 时执行区分大小写的匹配。

示例

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

自 1.5.0

sum

sum(表达式) - 返回从组值中计算出的总和。

示例

> 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(表达式) - 返回表达式的正切值，如同由 java.lang.Math.tan 计算。

参数

expr - 弧度角

示例

> SELECT tan(0);
 0.0

自 1.4.0

tanh

tanh(表达式) - 返回表达式的双曲正切值，如同由 java.lang.Math.tanh 计算。

参数

expr - 双曲角

示例

> SELECT tanh(0);
 0.0

自 1.4.0

timestamp

timestamp(表达式) - 将表达式的值转换为目标数据类型 timestamp。

自 2.0.1

timestamp_micros

timestamp_micros(微秒) - 从 UTC 纪元以来的微秒数创建时间戳。

示例

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

自 3.1.0

timestamp_millis

timestamp_millis(毫秒) - 从 UTC 纪元以来的毫秒数创建时间戳。

示例

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

自 3.1.0

timestamp_seconds

timestamp_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(表达式) - 将表达式的值转换为目标数据类型 tinyint。

自 2.0.1

to_avro

to_avro(子元素[, JSON格式AvroSchema]) - 将 Catalyst 二进制输入值转换为相应的 Avro 格式结果。

示例

> SELECT to_avro(s, '{"type": "record", "name": "struct", "fields": [{ "name": "u", "type": ["int","string"] }]}') IS NULL FROM (SELECT NULL AS s);
 [true]
> SELECT to_avro(s) IS NULL FROM (SELECT NULL AS s);
 [true]

自 4.0.0

to_binary

to_binary(字符串[, 格式]) - 根据提供的 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(表达式, 格式) - 根据 format 将 expr 转换为字符串。如果转换失败，则抛出异常。格式可以由以下字符（不区分大小写）组成：'0' 或 '9'：指定一个预期的数字，范围在 0 到 9 之间。格式字符串中的一串 0 或 9 与输入值中的一串数字匹配，生成与格式字符串中相应序列长度相同的结果字符串。如果 0/9 序列包含的数字位数多于十进制值匹配部分的位数，并且以 0 开头且位于小数点之前，则结果字符串会用零左填充。否则，用空格填充。'.' 或 'D'：指定小数点的位置（可选，只允许出现一次）。',' 或 'G'：指定分组（千位）分隔符 (,) 的位置。每个分组分隔符的左侧和右侧必须有 0 或 9。'$'：指定 $ 货币符号的位置。此字符只能指定一次。'S' 或 'MI'：指定 '-' 或 '+' 符号的位置（可选，只允许在格式字符串的开头或结尾出现一次）。请注意，'S' 对正值打印 '+'，但 'MI' 打印空格。'PR'：只允许在格式字符串的末尾出现；指定如果输入值为负数，则结果字符串将用尖括号括起来（例如 '<1>'）。如果 expr 是日期时间类型，format 应为有效的日期时间模式，请参阅日期时间模式。如果 expr 是二进制类型，则将其转换为以下格式之一的字符串：'base64'：一个 base 64 字符串。'hex'：十六进制格式的字符串。'utf-8'：输入二进制解码为 UTF-8 字符串。

示例

> 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-
> SELECT to_char(date'2016-04-08', 'y');
 2016
> SELECT to_char(x'537061726b2053514c', 'base64');
 U3BhcmsgU1FM
> SELECT to_char(x'537061726b2053514c', 'hex');
 537061726B2053514C
> SELECT to_char(encode('abc', 'utf-8'), 'utf-8');
 abc

自 3.4.0

to_csv

to_csv(表达式[, 选项]) - 返回给定结构体值的 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(日期字符串[, 格式]) - 使用 fmt 表达式将 date_str 表达式解析为日期。无效输入返回 null。默认情况下，如果省略 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(表达式[, 选项]) - 返回给定结构体值的 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(表达式, 格式) - 根据字符串格式 '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_protobuf

to_protobuf(子元素, 消息名称, 描述文件路径, 选项) - 将 Catalyst 二进制输入值转换为相应的 Protobuf 格式结果。

示例

> SELECT to_protobuf(s, 'Person', '/path/to/descriptor.desc', map('emitDefaultValues', 'true')) IS NULL FROM (SELECT NULL AS s);
 [true]

自 4.0.0

to_timestamp

to_timestamp(时间戳字符串[, 格式]) - 使用 fmt 表达式将 timestamp_str 表达式解析为时间戳。无效输入返回 null。默认情况下，如果省略 fmt，则遵循转换为时间戳的转换规则。结果数据类型与配置 spark.sql.timestampType 的值保持一致。

参数

时间戳字符串 - 要解析为时间戳的字符串。
格式 - 要遵循的时间戳格式模式。有关有效的日期和时间格式模式，请参阅日期时间模式。

示例

> 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(时间戳字符串[, 格式]) - 使用 fmt 表达式将 timestamp_str 表达式解析为带本地时区的时间戳。无效输入返回 null。默认情况下，如果省略 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(时间戳字符串[, 格式]) - 使用 fmt 表达式将 timestamp_str 表达式解析为不带时区的时间戳。无效输入返回 null。默认情况下，如果省略 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(时间表达式[, 格式]) - 返回给定时间的 UNIX 时间戳。

参数

时间表达式 - 日期/时间戳或字符串，以 UNIX 时间戳形式返回。
格式 - 日期/时间格式模式。如果 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(时间戳, 时区) - 给定一个时间戳（例如 '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(表达式, 格式) - 根据 format 将 expr 转换为字符串。如果转换失败，则抛出异常。格式可以由以下字符（不区分大小写）组成：'0' 或 '9'：指定一个预期的数字，范围在 0 到 9 之间。格式字符串中的一串 0 或 9 与输入值中的一串数字匹配，生成与格式字符串中相应序列长度相同的结果字符串。如果 0/9 序列包含的数字位数多于十进制值匹配部分的位数，并且以 0 开头且位于小数点之前，则结果字符串会用零左填充。否则，用空格填充。'.' 或 'D'：指定小数点的位置（可选，只允许出现一次）。',' 或 'G'：指定分组（千位）分隔符 (,) 的位置。每个分组分隔符的左侧和右侧必须有 0 或 9。'$'：指定 $ 货币符号的位置。此字符只能指定一次。'S' 或 'MI'：指定 '-' 或 '+' 符号的位置（可选，只允许在格式字符串的开头或结尾出现一次）。请注意，'S' 对正值打印 '+'，但 'MI' 打印空格。'PR'：只允许在格式字符串的末尾出现；指定如果输入值为负数，则结果字符串将用尖括号括起来（例如 '<1>'）。如果 expr 是日期时间类型，format 应为有效的日期时间模式，请参阅日期时间模式。如果 expr 是二进制类型，则将其转换为以下格式之一的字符串：'base64'：一个 base 64 字符串。'hex'：十六进制格式的字符串。'utf-8'：输入二进制解码为 UTF-8 字符串。

示例

> 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-
> SELECT to_varchar(date'2016-04-08', 'y');
 2016
> SELECT to_varchar(x'537061726b2053514c', 'base64');
 U3BhcmsgU1FM
> SELECT to_varchar(x'537061726b2053514c', 'hex');
 537061726B2053514C
> SELECT to_varchar(encode('abc', 'utf-8'), 'utf-8');
 abc

自 3.5.0

to_variant_object

to_variant_object(表达式) - 将嵌套输入（数组/映射/结构体）转换为变体，其中映射和结构体被转换为变体对象，这些对象与 SQL 结构体不同，是无序的。输入映射只能有字符串键。

示例

> SELECT to_variant_object(named_struct('a', 1, 'b', 2));
 {"a":1,"b":2}
> SELECT to_variant_object(array(1, 2, 3));
 [1,2,3]
> SELECT to_variant_object(array(named_struct('a', 1)));
 [{"a":1}]
> SELECT to_variant_object(array(map("a", 2)));
 [{"a":2}]

自 4.0.0

to_xml

to_xml(表达式[, 选项]) - 返回给定结构体值的 XML 字符串

示例

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

自 4.0.0

transform

transform(表达式, 函数) - 使用函数转换数组中的元素。

示例

> 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(表达式, 函数) - 使用函数转换映射中的元素。

示例

> 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(表达式, 函数) - 使用函数转换映射中的值。

示例

> 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(输入, 源字符串, 目标字符串) - 通过将源字符串中存在的字符替换为目标字符串中相应的字符来翻译输入字符串。

示例

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

自 1.5.0

trim

trim(字符串) - 从字符串中移除前导和尾随的空格字符。

trim(BOTH FROM 字符串) - 从字符串中移除前导和尾随的空格字符。

trim(LEADING FROM 字符串) - 从字符串中移除前导空格字符。

trim(TRAILING FROM 字符串) - 从字符串中移除尾随空格字符。

trim(要修剪的字符串 FROM 字符串) - 从字符串中移除前导和尾随的 trimStr 字符。

trim(BOTH 要修剪的字符串 FROM 字符串) - 从字符串中移除前导和尾随的 trimStr 字符。

trim(LEADING 要修剪的字符串 FROM 字符串) - 从字符串中移除前导的 trimStr 字符。

trim(TRAILING 要修剪的字符串 FROM 字符串) - 从字符串中移除尾随的 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 指定的单位的日期。

参数

日期 - 日期值或有效日期字符串
fmt - 表示要截断到的单位的格式
- "YEAR", "YYYY", "YY" - 截断到日期所在的年份的第一天
- "QUARTER" - 截断到日期所在的季度的第一天
- "MONTH", "MM", "MON" - 截断到日期所在的月份的第一天
- "WEEK" - 截断到日期所在周的星期一

示例

> 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(表达式1, 表达式2) - 返回表达式1和表达式2的和，溢出时结果为 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(表达式, 密钥[, 模式[, 填充[, 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(表达式) - 返回从组值中计算出的平均值，溢出时结果为 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(被除数, 除数) - 返回 dividend/divisor。它总是执行浮点除法。如果 expr2 为 0，则结果始终为 null。dividend 必须是数值或间隔。divisor 必须是数值。

示例

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

try_make_interval([年[, 月[, 周[, 天[, 小时[, 分[, 秒]]]]]]]) - 这是 make_interval 的一个特殊版本，执行相同的操作，但发生溢出时返回 NULL。

参数

years - 年数，正数或负数
months - 月数，正数或负数
weeks - 周数，正数或负数
days - 天数，正数或负数
hours - 小时数，正数或负数
mins - 分钟数，正数或负数
secs - 秒数，带微秒精度的小数部分。

示例

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

自 4.0.0

try_make_timestamp

try_make_timestamp(年, 月, 日, 小时, 分钟, 秒[, 时区]) - 尝试从年、月、日、小时、分钟、秒和时区字段创建时间戳。结果数据类型与配置 spark.sql.timestampType 的值保持一致。无效输入时函数返回 NULL。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从0到60。该值可以是整数，如13，也可以是小数，如13.123。如果sec参数等于60，则秒字段设置为0，并在最终时间戳中增加1分钟。
timezone - 时区标识符。例如，CET、UTC等。

示例

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

自 4.0.0

try_make_timestamp_ltz

try_make_timestamp_ltz(年, 月, 日, 小时, 分钟, 秒[, 时区]) - 尝试从年、月、日、小时、分钟、秒和时区字段创建带本地时区的当前时间戳。无效输入时函数返回 NULL。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从0到60。如果sec参数等于60，则秒字段设置为0，并在最终时间戳中增加1分钟。
timezone - 时区标识符。例如，CET、UTC等。

示例

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

自 4.0.0

try_make_timestamp_ntz

try_make_timestamp_ntz(年, 月, 日, 小时, 分钟, 秒) - 尝试从年、月、日、小时、分钟、秒字段创建本地日期时间。无效输入时函数返回 NULL。

参数

year - 表示的年份，从1到9999
month - 表示的月份，从1（一月）到12（十二月）
day - 表示的月份中的日期，从1到31
hour - 表示的小时，从0到23
min - 表示的分钟，从0到59
sec - 表示的秒（带微秒小数部分），从0到60。如果sec参数等于60，则秒字段设置为0，并在最终时间戳中增加1分钟。

示例

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

自 4.0.0

try_mod

try_mod(被除数, 除数) - 返回表达式1除以表达式2后的余数。dividend 必须是数值。divisor 必须是数值。

示例

> SELECT try_mod(3, 2);
 1
> SELECT try_mod(2L, 2L);
 0
> SELECT try_mod(3.0, 2.0);
 1.0
> SELECT try_mod(1, 0);
 NULL

自 4.0.0

try_multiply

try_multiply(表达式1, 表达式2) - 返回表达式1*表达式2的结果，溢出时为 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_parse_json

try_parse_json(JSON字符串) - 将 JSON 字符串解析为 Variant 值。当字符串不是有效的 JSON 值时返回 NULL。

示例

> SELECT try_parse_json('{"a":1,"b":0.8}');
 {"a":1,"b":0.8}
> SELECT try_parse_json('{"a":1,');
 NULL

自 4.0.0

try_parse_url

try_parse_url(URL, 要提取的部分[, 键]) - 这是 parse_url 的一个特殊版本，执行相同的操作，但如果无法执行解析，则返回 NULL 值而不是引发错误。

示例

> SELECT try_parse_url('https://spark.apache.org/path?query=1', 'HOST');
 spark.apache.org
> SELECT try_parse_url('https://spark.apache.org/path?query=1', 'QUERY');
 query=1
> SELECT try_parse_url('inva lid://spark.apache.org/path?query=1', 'QUERY');
 NULL
> SELECT try_parse_url('https://spark.apache.org/path?query=1', 'QUERY', 'query');
 1

自 4.0.0

try_reflect

try_reflect(类, 方法[, 参数1[, 参数2 ..]]) - 这是 reflect 的一个特殊版本，执行相同的操作，但如果调用方法抛出异常，则返回 NULL 值而不是引发错误。

示例

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

自 4.0.0

try_subtract

try_subtract(表达式1, 表达式2) - 返回表达式1-表达式2的结果，溢出时为 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(表达式) - 返回从组值中计算出的总和，溢出时结果为 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(表达式, 格式) - 根据字符串格式 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 表达式将 timestamp_str 表达式解析为时间戳。无论是否启用 ANSI SQL 模式，该函数在无效输入时始终返回 null。默认情况下，如果省略 fmt，则遵循转换为时间戳的转换规则。结果数据类型与配置 spark.sql.timestampType 的值保持一致。

参数

时间戳字符串 - 要解析为时间戳的字符串。
格式 - 要遵循的时间戳格式模式。有关有效的日期和时间格式模式，请参阅日期时间模式。

示例

> 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

try_url_decode

try_url_decode(字符串) - 这是 url_decode 的一个特殊版本，执行相同的操作，但如果无法执行解码，则返回 NULL 值而不是引发错误。

参数

字符串 - 要解码的字符串表达式

示例

> SELECT try_url_decode('https%3A%2F%2Fspark.apache.org');
 https://spark.apache.org

自 4.0.0

try_validate_utf8

try_validate_utf8(字符串) - 如果字符串是有效的 UTF-8 字符串，则返回原始字符串，否则返回 NULL。

参数

str - 字符串表达式

示例

> SELECT try_validate_utf8('Spark');
 Spark
> SELECT try_validate_utf8(x'61');
 a
> SELECT try_validate_utf8(x'80');
 NULL
> SELECT try_validate_utf8(x'61C262');
 NULL

自 4.0.0

try_variant_get

try_variant_get(变体, 路径[, 类型]) - 根据 path 从 v 中提取子变体，然后将子变体转换为 type。如果省略 type，则默认为 variant。如果路径不存在或转换失败，则返回 null。

示例

> SELECT try_variant_get(parse_json('{"a": 1}'), '$.a', 'int');
 1
> SELECT try_variant_get(parse_json('{"a": 1}'), '$.b', 'int');
 NULL
> SELECT try_variant_get(parse_json('[1, "2"]'), '$[1]', 'string');
 2
> SELECT try_variant_get(parse_json('[1, "2"]'), '$[2]', 'string');
 NULL
> SELECT try_variant_get(parse_json('[1, "hello"]'), '$[1]');
 "hello"
> SELECT try_variant_get(parse_json('[1, "hello"]'), '$[1]', 'int');
 NULL

自 4.0.0

typeof

typeof(表达式) - 返回输入数据类型的 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 字符串 str 转换为二进制。

示例

> SELECT unbase64('U3BhcmsgU1FM');
 Spark SQL

自 1.5.0

unhex

unhex(表达式) - 将十六进制表达式转换为二进制。

示例

> SELECT decode(unhex('537061726B2053514C'), 'UTF-8');
 Spark SQL

自 1.5.0

uniform

uniform(最小值, 最大值[, 种子]) - 返回一个随机值，该值具有独立同分布 (i.i.d.) 且在指定数字范围内的值。随机种子是可选的。提供的指定范围最小值和最大值的数字必须是常量。如果这两个数字都是整数，则结果也将是整数。否则，如果其中一个或两个都是浮点数，则结果也将是浮点数。

示例

> SELECT uniform(10, 20, 0) > 0 AS result;
true

自 4.0.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 时间戳。

参数

时间表达式 - 日期/时间戳或字符串。如果未提供，则默认为当前时间。
格式 - 日期/时间格式模式。如果 timeExp 不是字符串，则忽略。默认值为 "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.apache.org

自 3.4.0

url_encode

url_encode(字符串) - 使用特定编码方案将字符串转换为“application/x-www-form-urlencoded”格式。

参数

字符串 - 要转换的字符串表达式

示例

> SELECT url_encode('https://spark.apache.org');
 https%3A%2F%2Fspark.apache.org

自 3.4.0

user

user() - 当前执行上下文的用户名。

示例

> SELECT user();
 mockingjay

自 3.4.0

uuid

uuid() - 返回一个通用唯一标识符 (UUID) 字符串。该值以规范的 UUID 36 字符字符串形式返回。

示例

> SELECT uuid();
 46707d92-02f4-4817-8116-a4c3b23e6266

注意

该函数是非确定性的。

自 2.3.0

validate_utf8

validate_utf8(字符串) - 如果字符串是有效的 UTF-8 字符串，则返回原始字符串，否则抛出异常。

参数

str - 字符串表达式

示例

> SELECT validate_utf8('Spark');
 Spark
> SELECT validate_utf8(x'61');
 a

自 4.0.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

variant_explode

variant_explode(表达式) - 它将变体对象/数组拆分为包含其字段/元素的多个行。其结果模式为 struct<pos int, key string, value variant>。pos 是字段/元素在其父对象/数组中的位置，value 是字段/元素值。key 是展开变体对象时的字段名，或在展开变体数组时为 NULL。它忽略任何非变体数组/对象的输入，包括 SQL NULL、变体 null 和任何其他变体值。

示例

> SELECT * from variant_explode(parse_json('["hello", "world"]'));
 0  NULL    "hello"
 1  NULL    "world"
> SELECT * from variant_explode(input => parse_json('{"a": true, "b": 3.14}'));
 0  a   true
 1  b   3.14

自 4.0.0

variant_explode_outer

variant_explode_outer(表达式) - 它将变体对象/数组拆分为包含其字段/元素的多个行。其结果模式为 struct<pos int, key string, value variant>。pos 是字段/元素在其父对象/数组中的位置，value 是字段/元素值。key 是展开变体对象时的字段名，或在展开变体数组时为 NULL。它忽略任何非变体数组/对象的输入，包括 SQL NULL、变体 null 和任何其他变体值。

示例

> SELECT * from variant_explode_outer(parse_json('["hello", "world"]'));
 0  NULL    "hello"
 1  NULL    "world"
> SELECT * from variant_explode_outer(input => parse_json('{"a": true, "b": 3.14}'));
 0  a   true
 1  b   3.14

自 4.0.0

variant_get

variant_get(变体, 路径[, 类型]) - 根据 path 从 v 中提取子变体，然后将子变体转换为 type。如果省略 type，则默认为 variant。如果路径不存在，则返回 null。如果转换失败，则抛出异常。

示例

> SELECT variant_get(parse_json('{"a": 1}'), '$.a', 'int');
 1
> SELECT variant_get(parse_json('{"a": 1}'), '$.b', 'int');
 NULL
> SELECT variant_get(parse_json('[1, "2"]'), '$[1]', 'string');
 2
> SELECT variant_get(parse_json('[1, "2"]'), '$[2]', 'string');
 NULL
> SELECT variant_get(parse_json('[1, "hello"]'), '$[1]');
 "hello"

自 4.0.0

version

version() - 返回 Spark 版本。该字符串包含 2 个字段，第一个是发布版本，第二个是 Git 修订版本。

示例

> SELECT version();
 3.1.0 a6d6ea3efedbad14d99c24143834cd4e2e52fb40

自 3.0.0

weekday

weekday(日期) - 返回日期/时间戳的星期几（0 = 星期一，1 = 星期二，...，6 = 星期日）。

示例

> SELECT weekday('2009-07-30');
 3

自 2.4.0

weekofyear

weekofyear(日期) - 返回给定日期的年份周数。一周被视为从星期一开始，第 1 周是第一个包含超过 3 天的周。

示例

> SELECT weekofyear('2008-02-20');
 8

自 1.5.0

when

CASE WHEN 表达式1 THEN 表达式2 [WHEN 表达式3 THEN 表达式4]* [ELSE 表达式5] END - 当 expr1 = true 时，返回 expr2；否则当 expr3 = true 时，返回 expr4；否则返回 expr5。

参数

表达式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

width_bucket(值, 最小值, 最大值, 桶数量) - 返回在最小值到最大值范围内，具有 num_bucket 个桶的等宽直方图中，value 将被分配到的桶号。

示例

> 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

window(时间列, 窗口持续时间[, 滑动持续时间[, 开始时间]]) - 根据时间戳指定列，将行分桶到一个或多个时间窗口中。窗口开始是包含的，但窗口结束是排他的，例如 12:05 将在窗口 [12:05,12:10) 中，但不在 [12:00,12:05) 中。窗口支持微秒精度。不支持按月排序的窗口。有关详细说明和示例，请参阅结构化流指南文档中的“事件时间上的窗口操作”。

参数

时间列 - 用作按时间分窗的时间戳的列或表达式。时间列必须是 TimestampType 类型。
窗口持续时间 - 一个字符串，指定窗口的宽度，表示为“间隔值”。（有关详细信息，请参阅间隔字面量。）请注意，持续时间是固定的时间长度，不随日历时间变化。
滑动持续时间 - 一个字符串，指定窗口的滑动间隔，表示为“间隔值”。每隔 slide_duration 会生成一个新窗口。必须小于或等于 window_duration。此持续时间同样是绝对的，不随日历变化。
开始时间 - 相对于 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_time(窗口列) - 从时间/会话窗口列中提取时间值，该值可用作窗口的事件时间值。提取的时间是 (window.end - 1)，这反映了聚合窗口具有排他性上限的事实 - [start, end) 有关详细说明和示例，请参阅结构化流指南文档中的“事件时间上的窗口操作”。

参数

窗口列 - 表示时间/会话窗口的列。

示例

> 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) - 返回 XML 节点中与 XPath 表达式匹配的值的字符串数组。

示例

> 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"]
> SELECT xpath('<a><b>b1</b><b>b2</b><b>b3</b><c>c1</c><c>c2</c></a>','a/b');
 [null,null,null]

自 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(表达式1, 表达式2, ...) - 返回参数的 64 位哈希值。哈希种子为 42。

示例

> SELECT xxhash64('Spark', array(123), 2);
 5602566077635097486

自 3.0.0

year

year(日期) - 返回日期/时间戳的年份部分。

示例

> SELECT year('2016-07-30');
 2016

自 1.5.0

zeroifnull

zeroifnull(表达式) - 如果表达式等于 null，则返回零；否则返回表达式。

示例

> SELECT zeroifnull(NULL);
 0
> SELECT zeroifnull(2);
 2

自 4.0.0

zip_with

zip_with(左数组, 右数组, 函数) - 使用函数将两个给定数组按元素合并为一个数组。如果一个数组较短，则在应用函数之前，会在末尾追加 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

|

表达式1 | 表达式2 - 返回表达式1和表达式2按位或的结果。

示例

> SELECT 3 | 5;
 7

自 1.4.0

||

表达式1 || 表达式2 - 返回表达式1和表达式2的串联。

示例

> 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

~

~ 表达式 - 返回表达式按位非的结果。

示例

> SELECT ~ 0;
 -1

自 1.4.0