系统（内置）函数 #

• numeric

• numeric

将十六进制字符串 expr 转换为 BINARY。

如果 expr 的长度为奇数，则会舍弃第一个字符，并在结果开头补充一个空字节。

expr <CHAR | VARCHAR>

返回一个 BINARY。如果 expr 为 NULL 或包含非十六进制字符，则返回 NULL。

返回 expr 的 percentage 百分位值。

percentage 必须是一个在 [0.0, 1.0] 之间的字面数值，或者是一个该范围的数组。 如果传递了一个可变表达式给这个函数，结果将根据其中的任意一个值进行计算。 frequency 描述了 expr 的统计次数，默认值为 1。

如果没有 expr 恰好位于指定的百分位上，则结果通过对两个最接近的 expr 进行线性插值来计算。 如果 expr 或 frequency 为 NULL，或者 frequency 不是正数，则将忽略该输入行。

注意: 建议在窗口场景中使用此函数，因为它通常能提供更好的性能。 在常规的分组聚合场景中，用户应注意每条记录引发的全面排序带来的性能开销。

value <NUMERIC>, percentage [<NUMERIC NOT NULL> | <ARRAY<NUMERIC NOT NULL> NOT NULL>], frequency <INTEGER_NUMERIC> (INTEGER_NUMERIC: TINYINT, SMALLINT, INTEGER, BIGINT) (NUMERIC: INTEGER_NUMERIC, FLOAT, DOUBLE, DECIMAL)

如果 percentage 是数字，返回类型为 DOUBLE；如果 percentage 是数组，返回类型为 ARRAY<DOUBLE>。 如果 percentage 是空数组，则返回 NULL。

格式化 print-style 样式的字符串。

函数使用 java.util.Formatter (Locale.US) 解析字符串。

null obj 被格式化为字符串 “null”。

strfmt <CHAR | VARCHAR>, obj

返回一个 STRING 格式的格式化后的字符串。如果 format 为 NULL 或不合法，则返回 NULL。

从 str 的开头删除 trimStr 中的字符。trimStr 默认设置为空格。

例如 ' This is a test String.'.ltrim() 返回 'This is a test String.'。

str <CHAR | VARCHAR>, trimStr <CHAR | VARCHAR>

返回一个 STRING 格式的裁剪后的 str。如果任何参数为 NULL，则返回 NULL。

从 str 的结尾删除 trimStr 中的字符。trimStr 默认设置为空格。

例如 'This is a test String. '.rtrim() 返回 'This is a test String.'。

str <CHAR | VARCHAR>, trimStr <CHAR | VARCHAR>

返回一个 STRING 格式的裁剪后的 str。如果任何参数为 NULL，则返回 NULL。

从 str 的开头和结尾删除 trimStr 中的字符。trimStr 默认设置为空格。

str <CHAR | VARCHAR>, trimStr <CHAR | VARCHAR>

返回一个 STRING 格式的裁剪后的 str。如果任何参数为 NULL，则返回 NULL。

判断 expr 是否以 startExpr 开头。如果 startExpr 为空，则结果为 true。

expr 和 startExpr 应具有相同的类型。

expr <CHAR | VARCHAR>, startExpr <CHAR | VARCHAR>

expr <BINARY | VARBINARY>, startExpr <BINARY | VARBINARY>

返回一个 BOOLEAN。如果任意参数为 NULL，则返回 NULL。

判断 expr 是否以 endExpr 结尾。如果 endExpr 为空，则结果为 true。

expr 和 endExpr 应具有相同的类型。

expr <CHAR | VARCHAR>, endExpr <CHAR | VARCHAR>

expr <BINARY | VARBINARY>, endExpr <BINARY | VARBINARY>

返回一个 BOOLEAN。如果任意参数为 NULL，则返回 NULL。

返回字符串 str 匹配正则表达式模式 regex 的次数。regex 必须是一个 Java 正则表达式。

str <CHAR | VARCHAR>, regex <CHAR | VARCHAR>

返回一个 INTEGER 表示匹配成功的次数。如果任何参数为 NULL 或 regex 非法，则返回 NULL。

提取字符串 str 中与正则表达式 regex 匹配且与 extractIndex 组对应的所有子串。

regex 可以包含多个组。extractIndex 用于指示要提取哪个正则组，索引从 1 开始，也作为未指定时的默认值。0 表示匹配整个正则表达式。

str <CHAR | VARCHAR>, regex <CHAR | VARCHAR>, extractIndex <TINYINT | SMALLINT | INTEGER | BIGINT>

返回一个 ARRAY<STRING>，表示所有匹配的子串。如果任何参数为 NULL或非法，则返回 NULL。

返回 str 中第一个匹配 regex 的子字符串的索引。

结果索引从 1 开始，如果匹配失败则返回 0。

str <CHAR | VARCHAR>, regex <CHAR | VARCHAR>

返回一个 INTEGER 表示 str 中第一个匹配 regex 的子字符串索引。如果任何参数为 NULL 或 regex 非法，则返回 NULL。

返回 str 中第一个匹配 regex 的子字符串。

str <CHAR | VARCHAR>, regex <CHAR | VARCHAR>

返回一个 STRING 表示 str 中第一个匹配 regex 的子字符串。如果任何参数为 NULL 或 regex 非法或匹配失败，则返回 NULL。

将 expr 中所有出现在 fromStr 之中的字符替换为 toStr 中的相应字符。

如果 toStr 的长度短于 fromStr，则未匹配的字符将被移除。

expr <CHAR | VARCHAR>, fromStr <CHAR | VARCHAR>, toStr <CHAR | VARCHAR>

返回 STRING 格式的转换结果。

返回第 index 个表达式。index 必须是介于 1 和 表达式数量之间的整数。

index <TINYINT | SMALLINT | INTEGER | BIGINT>, expr <CHAR | VARCHAR>, exprs <CHAR | VARCHAR>

index <TINYINT | SMALLINT | INTEGER | BIGINT>, expr <BINARY | VARBINARY>, exprs <BINARY | VARBINARY>

结果类型为所有 expr 的公共类型。如果 index 为 NULL 或超出范围，则返回 NULL。

使用表配置中指定的时区将格式为 string2 的日期时间字符串 string1（如果未指定默认情况下：yyyy-MM-dd HH:mm:ss） 转换为 Unix 时间戳（以秒为单位）。

如果时间戳字符串指定了时区并使用 UTC+X 的格式解析（例如：“yyyy-MM-dd HH:mm:ss.SSS X”），此函数将会使用时间戳字符串中的时区来转换，而不是 Flink 会话中所配置的时区。 如果时间戳字符串无法正常解析，此函数将会默认返回 Long.MIN_VALUE（即: -9223372036854775808）作为结果。

Flink SQL> SET 'table.local-time-zone' = 'Europe/Berlin';

-- 返回 25201
Flink SQL> SELECT UNIX_TIMESTAMP('1970-01-01 08:00:01.001', 'yyyy-MM-dd HH:mm:ss.SSS');
-- 返回 1
Flink SQL> SELECT UNIX_TIMESTAMP('1970-01-01 08:00:01.001 +0800', 'yyyy-MM-dd HH:mm:ss.SSS X');
-- 返回 25201
Flink SQL> SELECT UNIX_TIMESTAMP('1970-01-01 08:00:01.001 +0800', 'yyyy-MM-dd HH:mm:ss.SSS');
-- 返回 -9223372036854775808
Flink SQL> SELECT UNIX_TIMESTAMP('1970-01-01 08:00:01.001', 'yyyy-MM-dd HH:mm:ss.SSS X');

返回给定时间列属性 rowtime 的当前水印，如果管道中的当前操作没有可用的上游操作的公共水印时则为 NULL。 函数的返回类型被推断为与提供的时间列属性匹配，但调整后的精度为 3。例如时间列属性为 TIMESTAMP_LTZ(9)，则函数将返回 TIMESTAMP_LTZ(3)。

请注意，此函数可以返回 NULL，您可能必须考虑这种情况。例如，如果您想过滤掉迟到数据，您可以使用：

WHERE
  CURRENT_WATERMARK(ts) IS NULL
  OR ts > CURRENT_WATERMARK(ts)

｜ 从 value1, value2, … 返回第一个不为 NULL 的值。例如 COALESCE(3, 5, 3) 返回 3。 如果所有参数为 NULL，返回 NULL。返回类型是所有参数的限制最最少的通用类型，如果所有参数是可空的类型，返回类型也是可空的类型。

-- 返回 f0，f1中第一个非空的值，如果 f0 和 f1 都是 NULL，则返回 'default' COALESCE(f0, f1, 'default') ```

如果输入为 NULL，则返回 null_replacement；否则返回 input。

与 COALESCE 或 CASE WHEN 相比，此函数返回的数据类型在是否为空方面非常明确。返回的类型是两个参数的公共类型，但只有在 null_replacement 可为空时才能为可空类型。 该函数允许将可空的列传递到使用 NOT NULL 约束声明的函数或表中。

例如 IFNULL(nullable_column, 5) 一定不返回 NULL。

返回 value 被转换为类型 type 的新值。CAST错误会抛出异常并导致作业失败。为了处理错误，在使用可能失败的 CAST 操作时，例如 STRING 转换为 INT，建议使用 TRY_CAST 替代。 如果开启了 “table.exec.legacy-cast-behaviour”，CAST 行为将变得与 TRY_CAST 一致。

例如, CAST(‘42’ AS INT) 返回 42; CAST(NULL AS STRING) 返回字符串类型的 NULL; CAST(’non-number’ AS INT) 抛出异常且作业失败。

判定给定字符串是否为有效的 JSON。

指定可选参数 type 将会限制 JSON 对象所允许的类型。 如果字符串是有效的 JSON，但不是指定的类型，则返回 false。默认值为 VALUE。

-- TRUE
'1' IS JSON
'[]' IS JSON
'{}' IS JSON

-- TRUE
'"abc"' IS JSON
-- FALSE
'abc' IS JSON
NULL IS JSON

-- TRUE
'1' IS JSON SCALAR
-- FALSE
'1' IS JSON ARRAY
-- FALSE
'1' IS JSON OBJECT

-- FALSE
'{}' IS JSON SCALAR
-- FALSE
'{}' IS JSON ARRAY
-- TRUE
'{}' IS JSON OBJECT

判定 JSON 字符串是否满足给定的路径搜索条件。

如果要忽略错误行为，那么将 FALSE ON ERROR 设为默认值。

-- TRUE
SELECT JSON_EXISTS('{"a": true}', '$.a');
-- FALSE
SELECT JSON_EXISTS('{"a": true}', '$.b');
-- TRUE
SELECT JSON_EXISTS('{"a": [{ "b": 1 }]}',
  '$.a[0].b');

-- TRUE
SELECT JSON_EXISTS('{"a": true}',
  'strict $.b' TRUE ON ERROR);
-- FALSE
SELECT JSON_EXISTS('{"a": true}',
  'strict $.b' FALSE ON ERROR);

将值序列化为 JSON。

此函数返回一个包含序列化值的 JSON 字符串。如果值为 NULL，函数返回 NULL。

-- NULL
JSON_STRING(CAST(NULL AS INT))

-- '1'
JSON_STRING(1)
-- 'true'
JSON_STRING(TRUE)
-- '"Hello, World!"'
JSON_STRING('Hello, World!')
-- '[1,2]'
JSON_STRING(ARRAY[1, 2])

从 JSON 字符串中提取标量。

此方法搜索给定路径表达式的 JSON 字符串，如果该路径上的值是标量则返回该值。不能返回非标量值。默认情况下返回值类型为 STRING。 可以将 dataType 设置不同的类型，支持的类型如下所示:

• VARCHAR / STRING
• BOOLEAN
• INTEGER
• DOUBLE

对于空路径表达式或错误，可以将行为定义为返回 null、引发错误或返回定义的默认值。当省略时，默认为 NULL ON EMPTY 或 NULL ON ERROR。默认值可以是文字或表达式。如果默认值本身引发错误，就会造成 ON EMPTY 的错误行为，并引发 ON ERROR 的错误。

对于路径表达式中包含特殊字符（如空格），你可以使用['property'] 或 ["property"]来引用父对象中指定的属性。请确保在属性名两侧加上单引号或双引号。 当在 SQL 使用 JSON_VALUE 时，路径作为一个字符串参数已经被单引号引用了，因此你必须将属性名上的单引号转义，如JSON_VALUE('{"a b": "true"}', '$.[''a b'']')。

-- "true"
JSON_VALUE('{"a": true}', '$.a')

-- TRUE
JSON_VALUE('{"a": true}', '$.a' RETURNING BOOLEAN)

-- "false"
JSON_VALUE('{"a": true}', 'lax $.b'
    DEFAULT FALSE ON EMPTY)

-- "false"
JSON_VALUE('{"a": true}', 'strict $.b'
    DEFAULT FALSE ON ERROR)

-- 0.998D
JSON_VALUE('{"a.b": [0.998,0.996]}','$.["a.b"][0]'
    RETURNING DOUBLE)

-- "right"
JSON_VALUE('{"contains blank": "right"}', 'strict $.[''contains blank'']' NULL ON EMPTY DEFAULT 'wrong' ON ERROR)

从 JSON 字符串中提取 JSON 值。

结果总是以 STRING 的形式返回。目前尚不支持 RETURNING 子句。

wrappingBehavior 决定是否将提取的值包装到一个数组中，以及是否无条件地这样做，还是只有当值本身不是数组时才这样做。

onEmpty 和 onError 分别决定路径表达式为空或引发错误时的行为。默认情况下，这两种情况都会返回 null。其他选择是 使用空数组、空对象或引发错误。

-- '{ "b": 1 }'
JSON_QUERY('{ "a": { "b": 1 } }', '$.a')
-- '[1, 2]'
JSON_QUERY('[1, 2]', '$')
-- NULL
JSON_QUERY(CAST(NULL AS STRING), '$')
-- '["c1","c2"]'
JSON_QUERY('{"a":[{"c":"c1"},{"c":"c2"}]}',
    'lax $.a[*].c')

-- 将结果包装到数组中
-- '[{}]'
JSON_QUERY('{}', '$' WITH CONDITIONAL ARRAY WRAPPER)
-- '[1, 2]'
JSON_QUERY('[1, 2]', '$' WITH CONDITIONAL ARRAY WRAPPER)
-- '[[1, 2]]'
JSON_QUERY('[1, 2]', '$' WITH UNCONDITIONAL ARRAY WRAPPER)

-- 必须包装标量才能返回
-- NULL
JSON_QUERY(1, '$')
-- '[1]'
JSON_QUERY(1, '$' WITH CONDITIONAL ARRAY WRAPPER)

-- 路径表达式为空/存在错误时的行为
-- '{}'
JSON_QUERY('{}', 'lax $.invalid' EMPTY OBJECT ON EMPTY)
-- '[]'
JSON_QUERY('{}', 'strict $.invalid' EMPTY ARRAY ON ERROR)

将键值对列表构建为 JSON 对象字符串。

注意，键必须是非 NULL 字符串字面值，而值可以是任意表达式。

这个函数返回一个 JSON 字符串。ON NULL 行为定义了如何处理 NULL 值。如果省略，则默认为 NULL ON NULL。

值是由另一个 JSON 构造函数调用 (JSON_OBJECT，JSON_ARRAY) 直接插入所创建，而不是作为一个字符串。它允许构建嵌套的 JSON 结构。

-- '{}'
JSON_OBJECT()

-- '{"K1":"V1","K2":"V2"}'
JSON_OBJECT('K1' VALUE 'V1', 'K2' VALUE 'V2')

-- 表达式作为值
JSON_OBJECT('orderNo' VALUE orders.orderId)

-- ON NULL
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) NULL ON NULL)   -- '{"K1":null}'
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) ABSENT ON NULL) -- '{}'

-- '{"K1":{"K2":"V"}}'
JSON_OBJECT(
  KEY 'K1'
  VALUE JSON_OBJECT(
    KEY 'K2'
    VALUE 'V'
  )
)

将数值列表构建为 JSON 数组字符串。

这个函数返回一个 JSON 字符串，值可以是任意表达式。ON NULL 行为定义了如何处理 NULL 值。如果省略，则假定 ABSENT ON NULL 为默认值。

元素是由另一个 JSON 构造函数调用 (JSON_OBJECT，JSON_ARRAY) 直接插入所创建，而不是作为一个字符串。它允许构建嵌套的 JSON 结构。

-- '[]'
JSON_ARRAY()
-- '[1,"2"]'
JSON_ARRAY(1, '2')

-- 表达式作为值
JSON_ARRAY(orders.orderId)

-- ON NULL
JSON_ARRAY(CAST(NULL AS STRING) NULL ON NULL) -- '[null]'
JSON_ARRAY(CAST(NULL AS STRING) ABSENT ON NULL) -- '[]'

-- '[[1]]'
JSON_ARRAY(JSON_ARRAY(1))

implicit constructor with parenthesis

(value1 [, value2]*)

explicit ROW constructor with

ROW(value1 [, value2]*)

通过将 key-value 聚合到单个 JSON 对象中，构建 JSON 对象字符串。

键表达式必须返回不为空的字符串。值表达式可以是任意的，包括其他 JSON 函数。 如果值为 NULL，则 ON NULL 行为定义了要执行的操作。如果省略，默认情况下假定为 NULL ON NULL。

请注意，键必须是唯一的。如果一个键出现多次，将抛出一个错误。

目前在 OVER windows 中不支持此函数。

-- '{"Apple":2,"Banana":17,"Orange":0}'
SELECT
  JSON_OBJECTAGG(KEY product VALUE cnt)
FROM orders

通过将字段聚合到数组中构建 JSON 对象字符串。

项目表达式可以是任意的，包括其他 JSON 函数。如果值为 NULL，则 ON NULL 行为定义了要执行的操作。如果省略，默认情况下假定为 ABSENT ON NULL。

此函数目前不支持 OVER windows、未绑定的 session windows 或 hop windows。

-- '["Apple","Banana","Orange"]'
SELECT
  JSON_ARRAYAGG(product)
FROM orders