From 9f480dcd29b8786932e063b7c821a0e29470b75b Mon Sep 17 00:00:00 2001 From: Gustavo de Morais Date: Thu, 30 Jan 2025 13:16:21 +0100 Subject: [PATCH 1/4] [FLINK-37239][docs] Add examples for unhex, btrim, translate, elt and percentile --- docs/data/sql_functions.yml | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/data/sql_functions.yml b/docs/data/sql_functions.yml index 2ff7353ebd2bf..966ff8885c57f 100644 --- a/docs/data/sql_functions.yml +++ b/docs/data/sql_functions.yml @@ -241,9 +241,9 @@ arithmetic: - sql: UNHEX(expr) table: expr.unhex() description: | - Converts hexadecimal string expr to BINARY. + Converts hexadecimal string expr to BINARY. If the length of expr is odd, the first character is discarded and the result is left padded with a null byte. - If the length of expr is odd, the first character is discarded and the result is left padded with a null byte. + E.g., SELECT UNHEX('466C696E6B') or $('466C696E6B').unhex() returns 466C696E6B as BINARY. expr @@ -256,7 +256,9 @@ arithmetic: description: | Returns the exact percentile value of expr at the specified percentage in a group. - percentage must be a literal numeric value between `[0.0, 1.0]` or an array of such values. + E.g., SELECT PERCENTILE(age, 0.5) FROM (VALUES (0), (50), (100)) AS age or $('age').percentile(0.5) returns 50.0. + + The percentage must be a literal numeric value between `[0.0, 1.0]` or an array of such values. If a variable expression is passed to this function, the result will be calculated using any one of them. frequency describes how many times expr should be counted, the default value is 1. @@ -335,6 +337,8 @@ string: description: | Removes any leading and trailing characters within trimStr from str. trimStr is set to whitespace by default. + E.g., BTRIM(' www.apache.org ') or ' www.apache.org '.btrim() returns "www.apache.org", BTRIM('/www.apache.org/', '/') or ' www.apache.org '.btrim() returns "www.apache.org". + str , trimStr Returns a STRING representation of the trimmed str. `NULL` if any of the arguments are `NULL`. @@ -431,10 +435,10 @@ string: - sql: TRANSLATE(expr, fromStr, toStr) table: expr.translate(fromStr, toStr) description: | - Translate an expr where all characters in fromStr have been replaced with those in toStr. - - If toStr has a shorter length than fromStr, unmatched characters are removed. + Translate an expr where all characters in fromStr have been replaced with those in toStr. If toStr has a shorter length than fromStr, unmatched characters are removed. + E.g., SELECT TRANSLATE3('www.apache.org', 'wapcheorg', ' APCHEcom') or 'www.apache.org'.translate('wapcheorg', ' APCHEcom') returns " .APACHE.com". + `expr , fromStr , toStr ` Returns a `STRING` of translated expr. @@ -531,6 +535,8 @@ string: description: | Returns the index-th expression. index must be an integer between 1 and the number of expressions. + E.g., SELECT ELT(2, 'scala-1', 'java-2', 'go-3') or 2.elt('scala-1', 'java-2', 'go-3') returns "java-2". + index , expr , exprs index , expr , exprs From 3c08458ae0d1f748c97444e16e4fc34769823d64 Mon Sep 17 00:00:00 2001 From: Gustavo de Morais Date: Thu, 30 Jan 2025 14:10:53 +0100 Subject: [PATCH 2/4] [FLINK-37239][docs] Improve example for unhex --- docs/data/sql_functions.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/sql_functions.yml b/docs/data/sql_functions.yml index 966ff8885c57f..fcd5e1c4b901f 100644 --- a/docs/data/sql_functions.yml +++ b/docs/data/sql_functions.yml @@ -243,7 +243,7 @@ arithmetic: description: | Converts hexadecimal string expr to BINARY. If the length of expr is odd, the first character is discarded and the result is left padded with a null byte. - E.g., SELECT UNHEX('466C696E6B') or $('466C696E6B').unhex() returns 466C696E6B as BINARY. + E.g., SELECT DECODE(UNHEX('466C696E6B') , 'UTF-8' ) or '466C696E6B'.unhex().decode('UTF-8') returns "Flink". expr From 8f5a88de3bfc08abb81909666bf297c098be9819 Mon Sep 17 00:00:00 2001 From: Gustavo de Morais Date: Thu, 30 Jan 2025 14:31:48 +0100 Subject: [PATCH 3/4] [FLINK-37239][docs] Add examples to chinese document --- docs/data/sql_functions_zh.yml | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/data/sql_functions_zh.yml b/docs/data/sql_functions_zh.yml index 06f5ce34ef915..a4c09de3bf98d 100644 --- a/docs/data/sql_functions_zh.yml +++ b/docs/data/sql_functions_zh.yml @@ -299,9 +299,9 @@ arithmetic: - sql: UNHEX(expr) table: expr.unhex() description: | - 将十六进制字符串 expr 转换为 BINARY。 + 将十六进制字符串 expr 转换为 BINARY。如果 expr 的长度为奇数，则会舍弃第一个字符，并在结果开头补充一个空字节。 - 如果 expr 的长度为奇数，则会舍弃第一个字符，并在结果开头补充一个空字节。 + E.g., SELECT DECODE(UNHEX('466C696E6B') , 'UTF-8' ) or '466C696E6B'.unhex().decode('UTF-8') returns "Flink". expr @@ -317,6 +317,8 @@ arithmetic: table: expr.percentile(percentage[, frequency]) description: | 返回 expr 的 percentage 百分位值。 + + E.g., SELECT PERCENTILE(age, 0.5) FROM (VALUES (0), (50), (100)) AS age or $('age').percentile(0.5) returns 50.0. percentage 必须是一个在 `[0.0, 1.0]` 之间的字面数值，或者是一个该范围的数组。 如果传递了一个可变表达式给这个函数，结果将根据其中的任意一个值进行计算。 @@ -397,6 +399,8 @@ string: description: | 从 str 的开头和结尾删除 trimStr 中的字符。trimStr 默认设置为空格。 + E.g., BTRIM(' www.apache.org ') or ' www.apache.org '.btrim() returns "www.apache.org", BTRIM('/www.apache.org/', '/') or ' www.apache.org '.btrim() returns "www.apache.org". + str , trimStr 返回一个 STRING 格式的裁剪后的 str。如果任何参数为 `NULL`，则返回 `NULL`。 @@ -498,10 +502,10 @@ string: - sql: TRANSLATE(expr, fromStr, toStr) table: expr.translate(fromStr, toStr) description: | - 将 expr 中所有出现在 fromStr 之中的字符替换为 toStr 中的相应字符。 - - 如果 toStr 的长度短于 fromStr，则未匹配的字符将被移除。 + 将 expr 中所有出现在 fromStr 之中的字符替换为 toStr 中的相应字符。如果 toStr 的长度短于 fromStr，则未匹配的字符将被移除。 + E.g., SELECT TRANSLATE3('www.apache.org', 'wapcheorg', ' APCHEcom') or 'www.apache.org'.translate('wapcheorg', ' APCHEcom') returns " .APACHE.com". + `expr , fromStr , toStr ` 返回 `STRING` 格式的转换结果。 @@ -628,6 +632,8 @@ string: description: | 返回第 index 个表达式。index 必须是介于 1 和 表达式数量之间的整数。 + E.g., SELECT ELT(2, 'scala-1', 'java-2', 'go-3') or 2.elt('scala-1', 'java-2', 'go-3') returns "java-2". + index , expr , exprs index , expr , exprs From 771c400313193f724ea5b42a6448f2235e04ec86 Mon Sep 17 00:00:00 2001 From: Gustavo de Morais Date: Fri, 31 Jan 2025 19:27:47 +0100 Subject: [PATCH 4/4] [FLINK-37239][docs] Improve percentile example --- docs/data/sql_functions.yml | 4 ++-- docs/data/sql_functions_zh.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/data/sql_functions.yml b/docs/data/sql_functions.yml index fcd5e1c4b901f..b8bd01393b848 100644 --- a/docs/data/sql_functions.yml +++ b/docs/data/sql_functions.yml @@ -254,9 +254,9 @@ arithmetic: - sql: PERCENTILE(expr, percentage[, frequency]) table: expr.percentile(percentage[, frequency]) description: | - Returns the exact percentile value of expr at the specified percentage in a group. + Returns the percentile value of expr at the specified percentage using continuous distribution. - E.g., SELECT PERCENTILE(age, 0.5) FROM (VALUES (0), (50), (100)) AS age or $('age').percentile(0.5) returns 50.0. + E.g., SELECT PERCENTILE(age, 0.25) FROM (VALUES (10), (20), (30), (40)) AS age or $('age').percentile(0.25) returns 17.5 The percentage must be a literal numeric value between `[0.0, 1.0]` or an array of such values. If a variable expression is passed to this function, the result will be calculated using any one of them. diff --git a/docs/data/sql_functions_zh.yml b/docs/data/sql_functions_zh.yml index a4c09de3bf98d..23742d22c4c97 100644 --- a/docs/data/sql_functions_zh.yml +++ b/docs/data/sql_functions_zh.yml @@ -318,7 +318,7 @@ arithmetic: description: | 返回 expr 的 percentage 百分位值。 - E.g., SELECT PERCENTILE(age, 0.5) FROM (VALUES (0), (50), (100)) AS age or $('age').percentile(0.5) returns 50.0. + E.g., SELECT PERCENTILE(age, 0.25) FROM (VALUES (10), (20), (30), (40)) AS age or $('age').percentile(0.25) returns 17.5 percentage 必须是一个在 `[0.0, 1.0]` 之间的字面数值，或者是一个该范围的数组。 如果传递了一个可变表达式给这个函数，结果将根据其中的任意一个值进行计算。