diff --git a/docs/sql-manual/sql-functions/scalar-functions/string-functions/decode.md b/docs/sql-manual/sql-functions/scalar-functions/string-functions/decode.md new file mode 100644 index 0000000000000..43deb7a57b5c4 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/string-functions/decode.md @@ -0,0 +1,81 @@ +--- +{ + "title": "DECODE", + "language": "en", + "description": "Converts a VARBINARY value to a string using the specified character set for Hive-compatible character conversion." +} +--- + +## Description + +Converts a `VARBINARY` value to a string using the specified character set. Character set names are case-insensitive. The supported character sets are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16BE`, `UTF-16LE`, and `UTF-16`. + +## Syntax + +```sql +DECODE(, ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The binary value to decode. Type: VARBINARY. | +| `` | A string literal naming the character set used by the input bytes, or `NULL`. Supported values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16BE`, `UTF-16LE`, and `UTF-16`. A column or other expression is not allowed. | + +## Return Value + +Returns a `STRING` value containing the decoded text. + +- If `` is `NULL`, or `` is `NULL` and `` is valid, the function returns `NULL`. +- If `` is empty, the function returns an empty string. +- For `UTF-16`, the function recognizes big-endian (`FE FF`) and little-endian (`FF FE`) BOMs and removes the BOM from the result. Without a BOM, it decodes the input as big-endian. `UTF-16BE` and `UTF-16LE` always use their explicit byte order. +- If `` is unsupported, the function returns an error even when `` is `NULL`. If `` is malformed for the specified character set, the function also returns an error. + +## Example + +**Decode UTF-8 bytes** + +```sql +SELECT DECODE(CAST(UNHEX('E4B8AD') AS VARBINARY), 'UTF-8') AS decoded_text; +``` + +```text ++--------------+ +| decoded_text | ++--------------+ +| 中 | ++--------------+ +``` + +**Decode little-endian UTF-16 with a BOM** + +The lower-case character set name also demonstrates case-insensitive matching. + +```sql +SELECT DECODE(CAST(UNHEX('FFFE2D4E') AS VARBINARY), 'utf-16') AS decoded_text; +``` + +```text ++--------------+ +| decoded_text | ++--------------+ +| 中 | ++--------------+ +``` + +**NULL and empty input** + +```sql +SELECT + DECODE(CAST(NULL AS VARBINARY), 'UTF-8') IS NULL AS null_result, + DECODE(CAST(UNHEX('') AS VARBINARY), 'UTF-16') = '' AS empty_result; +``` + +```text ++-------------+--------------+ +| null_result | empty_result | ++-------------+--------------+ +| 1 | 1 | ++-------------+--------------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/string-functions/encode.md b/docs/sql-manual/sql-functions/scalar-functions/string-functions/encode.md new file mode 100644 index 0000000000000..25357c04c7b63 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/string-functions/encode.md @@ -0,0 +1,86 @@ +--- +{ + "title": "ENCODE", + "language": "en", + "description": "Converts a string to a VARBINARY value using the specified character set for Hive-compatible character conversion." +} +--- + +## Description + +Converts a string to a `VARBINARY` value using the specified character set. Character set names are case-insensitive. The supported character sets are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16BE`, `UTF-16LE`, and `UTF-16`. + +## Syntax + +```sql +ENCODE(, ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The string to encode. Type: STRING. | +| `` | A string literal naming the target character set, or `NULL`. Supported values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16BE`, `UTF-16LE`, and `UTF-16`. A column or other expression is not allowed. | + +## Return Value + +Returns a `VARBINARY` value containing the encoded bytes. + +- If `` is `NULL`, or `` is `NULL` and `` is valid, the function returns `NULL`. +- If `` is an empty string, the function returns an empty binary value. +- `UTF-16` writes a big-endian byte order mark (BOM) for a non-empty input. `UTF-16BE` and `UTF-16LE` do not write a BOM. +- If `` is unsupported, the function returns an error even when `` is `NULL`. If `` contains a character that cannot be represented by the target character set, the function also returns an error. + +## Example + +**Encode the same character using UTF-8 and ISO-8859-1** + +`HEX` is used to display the returned binary bytes. + +```sql +SELECT + HEX(ENCODE('é', 'UTF-8')) AS utf8_bytes, + HEX(ENCODE('é', 'ISO-8859-1')) AS latin1_bytes; +``` + +```text ++------------+--------------+ +| utf8_bytes | latin1_bytes | ++------------+--------------+ +| C3A9 | E9 | ++------------+--------------+ +``` + +**Compare the UTF-16 variants** + +```sql +SELECT + HEX(ENCODE('中', 'UTF-16BE')) AS big_endian, + HEX(ENCODE('中', 'UTF-16LE')) AS little_endian, + HEX(ENCODE('中', 'UTF-16')) AS with_bom; +``` + +```text ++------------+---------------+----------+ +| big_endian | little_endian | with_bom | ++------------+---------------+----------+ +| 4E2D | 2D4E | FEFF4E2D | ++------------+---------------+----------+ +``` + +**NULL and empty input** + +```sql +SELECT + ENCODE(NULL, 'UTF-8') IS NULL AS null_result, + HEX(ENCODE('', 'UTF-16')) = '' AS empty_result; +``` + +```text ++-------------+--------------+ +| null_result | empty_result | ++-------------+--------------+ +| 1 | 1 | ++-------------+--------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/decode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/decode.md new file mode 100644 index 0000000000000..fe8357cc47bfa --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/decode.md @@ -0,0 +1,81 @@ +--- +{ + "title": "DECODE", + "language": "zh-CN", + "description": "DECODE 函数使用指定字符集将 VARBINARY 字节值转换为字符串,支持 US-ASCII、ISO-8859-1、UTF-8、UTF-16BE、UTF-16LE 和 UTF-16。" +} +--- + +## 描述 + +使用指定字符集将 `VARBINARY` 值转换为字符串。字符集名称不区分大小写。支持的字符集包括 `US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。 + +## 语法 + +```sql +DECODE(, ) +``` + +## 参数 + +| 参数 | 说明 | +| :--- | :--- | +| `` | 要解码的二进制值。类型:VARBINARY。 | +| `` | 输入字节所使用的字符集名称的字符串字面量,或 `NULL`。支持的值为 `US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。不允许使用列或其他表达式。 | + +## 返回值 + +返回包含解码后文本的 `STRING` 值。 + +- `` 为 `NULL`,或 `` 为 `NULL` 且 `` 有效时,返回 `NULL`。 +- `` 为空时,返回空字符串。 +- 对于 `UTF-16`,函数识别大端(`FE FF`)和小端(`FF FE`)BOM,并从结果中移除 BOM。没有 BOM 时,按大端解码。`UTF-16BE` 和 `UTF-16LE` 始终使用各自明确的字节序。 +- `` 不受支持时,即使 `` 为 `NULL`,函数也会返回错误。`` 对于指定字符集格式不正确时,函数同样返回错误。 + +## 示例 + +**解码 UTF-8 字节** + +```sql +SELECT DECODE(CAST(UNHEX('E4B8AD') AS VARBINARY), 'UTF-8') AS decoded_text; +``` + +```text ++--------------+ +| decoded_text | ++--------------+ +| 中 | ++--------------+ +``` + +**解码带 BOM 的小端 UTF-16 字节** + +小写字符集名称同时说明字符集匹配不区分大小写。 + +```sql +SELECT DECODE(CAST(UNHEX('FFFE2D4E') AS VARBINARY), 'utf-16') AS decoded_text; +``` + +```text ++--------------+ +| decoded_text | ++--------------+ +| 中 | ++--------------+ +``` + +**NULL 和空输入** + +```sql +SELECT + DECODE(CAST(NULL AS VARBINARY), 'UTF-8') IS NULL AS null_result, + DECODE(CAST(UNHEX('') AS VARBINARY), 'UTF-16') = '' AS empty_result; +``` + +```text ++-------------+--------------+ +| null_result | empty_result | ++-------------+--------------+ +| 1 | 1 | ++-------------+--------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/encode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/encode.md new file mode 100644 index 0000000000000..405f8289e5568 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/encode.md @@ -0,0 +1,86 @@ +--- +{ + "title": "ENCODE", + "language": "zh-CN", + "description": "ENCODE 函数使用指定字符集将字符串转换为 VARBINARY 字节值,支持 US-ASCII、ISO-8859-1、UTF-8、UTF-16BE、UTF-16LE 和 UTF-16。" +} +--- + +## 描述 + +使用指定字符集将字符串转换为 `VARBINARY` 值。字符集名称不区分大小写。支持的字符集包括 `US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。 + +## 语法 + +```sql +ENCODE(, ) +``` + +## 参数 + +| 参数 | 说明 | +| :--- | :--- | +| `` | 要编码的字符串。类型:STRING。 | +| `` | 目标字符集名称的字符串字面量,或 `NULL`。支持的值为 `US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。不允许使用列或其他表达式。 | + +## 返回值 + +返回包含编码后字节的 `VARBINARY` 值。 + +- `` 为 `NULL`,或 `` 为 `NULL` 且 `` 有效时,返回 `NULL`。 +- `` 为空字符串时,返回空的二进制值。 +- 对于非空输入,`UTF-16` 会写入大端字节序标记(BOM)。`UTF-16BE` 和 `UTF-16LE` 不写入 BOM。 +- `` 不受支持时,即使 `` 为 `NULL`,函数也会返回错误。`` 包含无法用目标字符集表示的字符时,函数同样返回错误。 + +## 示例 + +**使用 UTF-8 和 ISO-8859-1 编码同一个字符** + +使用 `HEX` 显示返回的二进制字节。 + +```sql +SELECT + HEX(ENCODE('é', 'UTF-8')) AS utf8_bytes, + HEX(ENCODE('é', 'ISO-8859-1')) AS latin1_bytes; +``` + +```text ++------------+--------------+ +| utf8_bytes | latin1_bytes | ++------------+--------------+ +| C3A9 | E9 | ++------------+--------------+ +``` + +**比较 UTF-16 的不同形式** + +```sql +SELECT + HEX(ENCODE('中', 'UTF-16BE')) AS big_endian, + HEX(ENCODE('中', 'UTF-16LE')) AS little_endian, + HEX(ENCODE('中', 'UTF-16')) AS with_bom; +``` + +```text ++------------+---------------+----------+ +| big_endian | little_endian | with_bom | ++------------+---------------+----------+ +| 4E2D | 2D4E | FEFF4E2D | ++------------+---------------+----------+ +``` + +**NULL 和空输入** + +```sql +SELECT + ENCODE(NULL, 'UTF-8') IS NULL AS null_result, + HEX(ENCODE('', 'UTF-16')) = '' AS empty_result; +``` + +```text ++-------------+--------------+ +| null_result | empty_result | ++-------------+--------------+ +| 1 | 1 | ++-------------+--------------+ +``` diff --git a/sidebars.ts b/sidebars.ts index cdb908dc63d6b..0feacdc21cefc 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1530,9 +1530,11 @@ const sidebars: SidebarsConfig = { 'sql-manual/sql-functions/scalar-functions/string-functions/count_substrings', 'sql-manual/sql-functions/scalar-functions/string-functions/cut-to-first-significant-subdomain', 'sql-manual/sql-functions/scalar-functions/string-functions/damerau_levenshtein_distance', + 'sql-manual/sql-functions/scalar-functions/string-functions/decode', 'sql-manual/sql-functions/scalar-functions/string-functions/digital-masking', 'sql-manual/sql-functions/scalar-functions/string-functions/domain', 'sql-manual/sql-functions/scalar-functions/string-functions/domain-without-www', + 'sql-manual/sql-functions/scalar-functions/string-functions/encode', 'sql-manual/sql-functions/scalar-functions/string-functions/ends-with', 'sql-manual/sql-functions/scalar-functions/string-functions/export-set', 'sql-manual/sql-functions/scalar-functions/string-functions/elt',