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 031ef2f967e [fix](doc) function/desc pages: add missing setup so
examples are reproducible (4 pages) (#3822)
031ef2f967e is described below
commit 031ef2f967e1b6b1aa12eab4312a86a69cf7f52d
Author: boluor <[email protected]>
AuthorDate: Wed May 27 21:32:05 2026 -0700
[fix](doc) function/desc pages: add missing setup so examples are
reproducible (4 pages) (#3822)
## Summary
Four pages on the 4.x doc referenced tables their example sections never
created. A fresh-cluster copy-paste of the example failed with \"Table
... does not exist\". This PR adds a small \`CREATE TABLE + INSERT\`
block scoped to each page's example needs, and updates the expected
output where the new setup produces a different (but representative)
value.
Each change is mirrored on both the EN and ZH version of the page.
| File | What was missing | What this PR adds |
|------|------------------|-------------------|
| \`bitmap-functions/bitmap-hash.md\` | \`words\` table |
4-distinct-value sample table; expected \`bitmap_count\` updated from
\`33263478\` (an unreproducible illustration) to \`4\`, with a prose
note that production-scale data can return much larger numbers |
| \`encrypt-digest-functions/sha2.md\` | \`str(k0 VARCHAR, k1 INT)\`
table | tiny setup so the two \"second-arg-must-be-literal\" error
examples actually run and produce the documented error string. Also adds
a one-sentence \"illustrative\" note in front of the two
\`mysql_catalog.binary_test.binary_test\` examples — they need an
external MySQL catalog most clusters do not have configured |
| \`array-functions/arrays-overlap.md\` | proper expected-error block
for the nested-arrays example | the existing leading \`--\` prose
comment is replaced with the actual 4.1.1 error string under the SELECT,
mirroring the format the rest of the page already uses |
| \`sql-statements/table-and-view/table/DESC-TABLE.md\` | \`test_table\`
itself | adds the CREATE block (user_id BIGINT, name VARCHAR, age INT,
with column comments). Both \`DESC test_table\` examples and the \`SET
show_column_comment_in_describe\` variant now reproduce the documented
result blocks byte-for-byte |
## Verification
Every added setup + example was run end-to-end on a single-node Apache
Doris 4.1.1 cluster; the result/error blocks in this PR are the verbatim
mysql client output.
## Note on a sibling page excluded
\`grouping-id.md\` was triaged together with these but is **not**
included. Its Example A uses \`ORDER BY GROUPING_ID(department, level)
ASC\`, which 4.1.1 rejects with \`LOGICAL_SORT can not contains
GroupingScalarFunction expression: Grouping_Id(department, level)\`.
Adding the missing \`employee\` setup table alone would not make the
example work — the SQL itself needs a rewrite or a planner change.
Flagged separately for RD.
## Test plan
- [x] Each new setup block executes on 4.1.1 and the following example
produces the documented result.
- [x] EN and ZH parallel-edited; structure mirrors between sides.
- [x] No existing examples removed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
.../scalar-functions/array-functions/arrays-overlap.md | 2 +-
.../scalar-functions/bitmap-functions/bitmap-hash.md | 12 ++++++++----
.../scalar-functions/encrypt-digest-functions/sha2.md | 12 ++++++++++++
.../sql-statements/table-and-view/table/DESC-TABLE.md | 13 +++++++++++++
.../scalar-functions/array-functions/arrays-overlap.md | 2 +-
.../scalar-functions/bitmap-functions/bitmap-hash.md | 12 ++++++++----
.../scalar-functions/encrypt-digest-functions/sha2.md | 12 ++++++++++++
.../sql-statements/table-and-view/table/DESC-TABLE.md | 13 +++++++++++++
8 files changed, 68 insertions(+), 10 deletions(-)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
index e4dc3eb8215..ea54652096b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
@@ -65,8 +65,8 @@ ARRAYS_OVERLAP(arr1, arr2)
2. 错误参数，当输入的参数是不支持的类型时，返回 `INVALID_ARGUMENT`
```SQL
- -- [INVALID_ARGUMENT]execute failed, unsupported types for function
arrays_overlap
SELECT ARRAYS_OVERLAP(ARRAY(ARRAY('hello', 'aloha'), ARRAY('hi', 'hey')),
ARRAY(ARRAY('hello', 'hi', 'hey'), ARRAY('aloha', 'hi')));
+ ERROR 1105 (HY000): errCode = 2, detailMessage = arrays_overlap does not
support types: ARRAY<ARRAY<TEXT>>
```
3. 输入的`ARRAY` 是 `NULL`，返回值是 `NULL`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
index cb1da1b66ed..e487b9d5440 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
@@ -53,19 +53,23 @@ select bitmap_to_array(bitmap_hash('hello'))[1];
+-------------------------------------------------------------+
```
-如果你想统计某一列去重后的个数，可以使用位图的方式，某些场景下性能比 `count distinct` 好很多：
+如果你想统计某一列去重后的个数，可以使用位图的方式，某些场景下性能比 `count distinct` 好很多。下面的示例先建一张 `words` 表，插入
6 行（其中 4 个去重值）；在真实大数据集上同样形态的查询可以返回到百万级别：
```sql
+CREATE TABLE `words` (`word` VARCHAR(64))
+DISTRIBUTED BY HASH(`word`) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO `words` VALUES ('apple'), ('banana'), ('cherry'), ('apple'),
('date'), ('banana');
+
select bitmap_count(bitmap_union(bitmap_hash(`word`))) from `words`;
```
-结果如下：
-
```text
+-------------------------------------------------+
| bitmap_count(bitmap_union(bitmap_hash(`word`))) |
+-------------------------------------------------+
-| 33263478 |
+| 4 |
+-------------------------------------------------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
index ec45414e6dc..a4414db2601 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
@@ -49,6 +49,16 @@ select sha2('abc', 225);
ERROR 1105 (HY000): errCode = 2, detailMessage = sha2 functions only support
digest length of [224, 256, 384, 512]
```
+第二个参数 `<digest_length>` 必须是字面量；即使值合法，传入列引用也会报错：
+
+```sql
+-- setup
+CREATE TABLE str (k0 VARCHAR(64), k1 INT)
+DISTRIBUTED BY HASH(k0) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+INSERT INTO str VALUES ('hello', 224), ('world', 256);
+```
+
```SQL
select sha2('str', k1) from str;
```
@@ -65,6 +75,8 @@ select sha2(k0, k1) from str;
ERROR 1105 (HY000): errCode = 2, detailMessage = the second parameter of sha2
must be a literal but got: k1
```
+下面两个示例是说明性的——它们需要一个名为 `mysql_catalog` 的外部 MySQL Catalog 中有
`binary_test.binary_test` 表，大多数集群未配置此环境。展示的是 `SHA2` 对内容相同的 `VARBINARY` 与
`VARCHAR` 列会输出相同摘要。
+
```sql
-- vb (VarBinary) 和 vc (VarChar) 插入时使用了相同的字符串.
SELECT * FROM mysql_catalog.binary_test.binary_test;
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
index 759f7420139..7e0fb7eb1a2 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
@@ -85,6 +85,19 @@ DESC[RIBE] [<ctl_name>.][<db_name>.]<table_name> [ALL];
## 举例
+准备 `test_table`，供下面的示例使用：
+
+```sql
+CREATE TABLE test_table (
+ user_id BIGINT NOT NULL COMMENT 'Key1',
+ name VARCHAR(20) COMMENT 'username',
+ age INT COMMENT 'user_age'
+) ENGINE=OLAP
+UNIQUE KEY (user_id)
+DISTRIBUTED BY HASH(user_id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+```
+
1. 显示 Base 表 Schema
```sql
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
index 83ce038c5ee..20ded879d23 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/arrays-overlap.md
@@ -64,8 +64,8 @@ ARRAYS_OVERLAP(arr1, arr2)
2. Invalid parameter type: when unsupported types are passed in, returns
`INVALID_ARGUMENT`
```SQL
- -- [INVALID_ARGUMENT] execute failed, unsupported types for function
arrays_overlap
SELECT ARRAYS_OVERLAP(ARRAY(ARRAY('hello', 'aloha'), ARRAY('hi', 'hey')),
ARRAY(ARRAY('hello', 'hi', 'hey'), ARRAY('aloha', 'hi')));
+ ERROR 1105 (HY000): errCode = 2, detailMessage = arrays_overlap does not
support types: ARRAY<ARRAY<TEXT>>
```
3. If the input `ARRAY` is `NULL`, the return value is `NULL`
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
index 182ba7f0658..fd6f371d404 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/bitmap-functions/bitmap-hash.md
@@ -53,19 +53,23 @@ The result will be:
+-------------------------------------------------------------+
```
-To count the distinct values in a column using bitmaps, which can be more
efficient than `count distinct` in some scenarios:
+To count the distinct values in a column using bitmaps, which can be more
efficient than `count distinct` in some scenarios. The example below populates
a `words` table with 6 rows containing 4 distinct values; at the doc-corpus
scale a real query of this shape can return numbers in the millions:
```sql
+CREATE TABLE `words` (`word` VARCHAR(64))
+DISTRIBUTED BY HASH(`word`) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO `words` VALUES ('apple'), ('banana'), ('cherry'), ('apple'),
('date'), ('banana');
+
select bitmap_count(bitmap_union(bitmap_hash(`word`))) from `words`;
```
-The result will be:
-
```text
+-------------------------------------------------+
| bitmap_count(bitmap_union(bitmap_hash(`word`))) |
+-------------------------------------------------+
-| 33263478 |
+| 4 |
+-------------------------------------------------+
```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
index c094b330ac2..44d8e132f3e 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/encrypt-digest-functions/sha2.md
@@ -49,6 +49,16 @@ select sha2('abc', 225);
ERROR 1105 (HY000): errCode = 2, detailMessage = sha2 functions only support
digest length of [224, 256, 384, 512]
```
+The second argument (`<digest_length>`) must be a literal; passing a column
reference fails even when the value would be valid:
+
+```sql
+-- setup
+CREATE TABLE str (k0 VARCHAR(64), k1 INT)
+DISTRIBUTED BY HASH(k0) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+INSERT INTO str VALUES ('hello', 224), ('world', 256);
+```
+
```SQL
select sha2('str', k1) from str;
```
@@ -65,6 +75,8 @@ select sha2(k0, k1) from str;
ERROR 1105 (HY000): errCode = 2, detailMessage = the second parameter of sha2
must be a literal but got: k1
```
+The following two examples are illustrative — they require an external MySQL
catalog named `mysql_catalog` containing `binary_test.binary_test`, which most
clusters do not have configured. They demonstrate that `SHA2` hashes a
`VARBINARY` column and a `VARCHAR` column to the same digest when the
underlying bytes are equal.
+
```sql
-- vb (VarBinary) and vc (VarChar) used the same string during insertion.
SELECT * FROM mysql_catalog.binary_test.binary_test;
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
index deb9ce920d2..d27e87b508f 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/DESC-TABLE.md
@@ -85,6 +85,19 @@ Users executing this SQL command must have at least the
following permissions:
## Examples
+Setup — create the `test_table` used by the examples below:
+
+```sql
+CREATE TABLE test_table (
+ user_id BIGINT NOT NULL COMMENT 'Key1',
+ name VARCHAR(20) COMMENT 'username',
+ age INT COMMENT 'user_age'
+) ENGINE=OLAP
+UNIQUE KEY (user_id)
+DISTRIBUTED BY HASH(user_id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+```
+
1. Display Base Table Schema
```sql
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
