This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new b1e7c1a7150 [docs](function) Add encode and decode documentation
(#4151)
b1e7c1a7150 is described below
commit b1e7c1a7150d8b766fc05c9598d8421588e28532
Author: hacklu-tu <[email protected]>
AuthorDate: Sat Oct 17 05:38:53 2026 +0800
[docs](function) Add encode and decode documentation (#4151)
## Summary
Document ENCODE and DECODE character conversion, supported character
sets, UTF-16 byte order marks, NULL values, empty input, and invalid
input.
## Versions
- [x] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1 or older
Dev only. Both functions are registered on current Doris master and are
absent from branch-4.0, branch-4.1, and branch-4.2; no 4.x pages are
added.
## Languages
- [x] Chinese
- [x] English
## Validation
Reviewed against Doris master `88f22fd875e0be4dea2c58c53744f4074378a870`
and the corresponding current 4.0, 4.1, and 4.2 source branches. Rebased
onto website master `f582020241f825849ffa3b57fc3220cb674d28a7`.
- SQL function structure and internal-link checks passed for the final
changed pages.
- `git diff --check` passed.
- English and Chinese changes are synchronized. Remaining version-sync
notices are explained above.
- Doris and the website were not built; examples were checked against
source and existing regression expectations where available.
---------
Co-authored-by: morningman <[email protected]>
---
.../scalar-functions/string-functions/decode.md | 85 ++++++++++++++++++++
.../scalar-functions/string-functions/encode.md | 90 ++++++++++++++++++++++
.../scalar-functions/string-functions/decode.md | 85 ++++++++++++++++++++
.../scalar-functions/string-functions/encode.md | 90 ++++++++++++++++++++++
sidebars.ts | 2 +
5 files changed, 352 insertions(+)
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 00000000000..6ddc98cf07a
--- /dev/null
+++ b/docs/sql-manual/sql-functions/scalar-functions/string-functions/decode.md
@@ -0,0 +1,85 @@
+---
+{
+ "title": "DECODE",
+ "language": "en",
+ "description": "Converts a VARBINARY value to a string using the specified
character set for Hive-compatible character conversion."
+}
+---
+
+<version since="dev">
+
+</version>
+
+## 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(<binary>, <charset>)
+```
+
+## Parameters
+
+| Parameter | Description |
+| :--- | :--- |
+| `<binary>` | The binary value to decode. Type: VARBINARY. |
+| `<charset>` | 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 `<charset>` is `NULL`, or `<binary>` is `NULL` and `<charset>` is valid,
the function returns `NULL`.
+- If `<binary>` 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 `<charset>` is unsupported, the function returns an error even when
`<binary>` is `NULL`. If `<binary>` 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 00000000000..be2ecdbcf34
--- /dev/null
+++ b/docs/sql-manual/sql-functions/scalar-functions/string-functions/encode.md
@@ -0,0 +1,90 @@
+---
+{
+ "title": "ENCODE",
+ "language": "en",
+ "description": "Converts a string to a VARBINARY value using the specified
character set for Hive-compatible character conversion."
+}
+---
+
+<version since="dev">
+
+</version>
+
+## 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(<source>, <charset>)
+```
+
+## Parameters
+
+| Parameter | Description |
+| :--- | :--- |
+| `<source>` | The string to encode. Type: STRING. |
+| `<charset>` | 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 `<charset>` is `NULL`, or `<source>` is `NULL` and `<charset>` is valid,
the function returns `NULL`.
+- If `<source>` 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 `<charset>` is unsupported, the function returns an error even when
`<source>` is `NULL`. If `<source>` 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 00000000000..7266959d5c9
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/decode.md
@@ -0,0 +1,85 @@
+---
+{
+ "title": "DECODE",
+ "language": "zh-CN",
+ "description": "DECODE 函数使用指定字符集将 VARBINARY 字节值转换为字符串，支持
US-ASCII、ISO-8859-1、UTF-8、UTF-16BE、UTF-16LE 和 UTF-16。"
+}
+---
+
+<version since="dev">
+
+</version>
+
+## 描述
+
+使用指定字符集将 `VARBINARY` 值转换为字符串。字符集名称不区分大小写。支持的字符集包括
`US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。
+
+## 语法
+
+```sql
+DECODE(<binary>, <charset>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+| :--- | :--- |
+| `<binary>` | 要解码的二进制值。类型：VARBINARY。 |
+| `<charset>` | 输入字节所使用的字符集名称的字符串字面量，或 `NULL`。支持的值为
`US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。不允许使用列或其他表达式。 |
+
+## 返回值
+
+返回包含解码后文本的 `STRING` 值。
+
+- `<charset>` 为 `NULL`，或 `<binary>` 为 `NULL` 且 `<charset>` 有效时，返回 `NULL`。
+- `<binary>` 为空时，返回空字符串。
+- 对于 `UTF-16`，函数识别大端（`FE FF`）和小端（`FF FE`）BOM，并从结果中移除 BOM。没有 BOM
时，按大端解码。`UTF-16BE` 和 `UTF-16LE` 始终使用各自明确的字节序。
+- `<charset>` 不受支持时，即使 `<binary>` 为 `NULL`，函数也会返回错误。`<binary>`
对于指定字符集格式不正确时，函数同样返回错误。
+
+## 示例
+
+**解码 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 00000000000..12abeadce9b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/encode.md
@@ -0,0 +1,90 @@
+---
+{
+ "title": "ENCODE",
+ "language": "zh-CN",
+ "description": "ENCODE 函数使用指定字符集将字符串转换为 VARBINARY 字节值，支持
US-ASCII、ISO-8859-1、UTF-8、UTF-16BE、UTF-16LE 和 UTF-16。"
+}
+---
+
+<version since="dev">
+
+</version>
+
+## 描述
+
+使用指定字符集将字符串转换为 `VARBINARY` 值。字符集名称不区分大小写。支持的字符集包括
`US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。
+
+## 语法
+
+```sql
+ENCODE(<source>, <charset>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+| :--- | :--- |
+| `<source>` | 要编码的字符串。类型：STRING。 |
+| `<charset>` | 目标字符集名称的字符串字面量，或 `NULL`。支持的值为
`US-ASCII`、`ISO-8859-1`、`UTF-8`、`UTF-16BE`、`UTF-16LE` 和 `UTF-16`。不允许使用列或其他表达式。 |
+
+## 返回值
+
+返回包含编码后字节的 `VARBINARY` 值。
+
+- `<charset>` 为 `NULL`，或 `<source>` 为 `NULL` 且 `<charset>` 有效时，返回 `NULL`。
+- `<source>` 为空字符串时，返回空的二进制值。
+- 对于非空输入，`UTF-16` 会写入大端字节序标记（BOM）。`UTF-16BE` 和 `UTF-16LE` 不写入 BOM。
+- `<charset>` 不受支持时，即使 `<source>` 为 `NULL`，函数也会返回错误。`<source>`
包含无法用目标字符集表示的字符时，函数同样返回错误。
+
+## 示例
+
+**使用 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 27c9d6c1e0a..6f2316de10f 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1557,9 +1557,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',
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
