[fix](sql-functions) provide setup data for FIELD examples (3.x / 2.1 + dev zh)

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/other-functions/field.md

@@ -29,6 +29,28 @@ FIELD(<expr>, <param> [, ...])
 
 ## 举例
 
+```sql
+-- setup
+CREATE TABLE baseall (k1 INT, k7 VARCHAR(64))
+DISTRIBUTED BY HASH(k1) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO baseall VALUES
+    (1, 'wangjing04'),
+    (2, 'wangyu14'),
+    (3, 'yuanyuan06');
+
+CREATE TABLE class_test (class_name VARCHAR(64))
+DISTRIBUTED BY HASH(class_name) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO class_test VALUES
+    ('Suzi'), ('Suzi'),
+    ('Ben'), ('Ben'),
+    ('Henry'), ('Henry'),
+    (NULL);
+```
+
 直接使用 `FIELD` 查找位置（基于 1 的索引）：
 
 ```sql
@@ -65,6 +87,7 @@ SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Hen
 +------------+
 | class_name |
 +------------+
+| NULL       |
 | Suzi       |
 | Suzi       |
 | Ben        |
@@ -88,6 +111,7 @@ SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Hen
 | Ben        |
 | Suzi       |
 | Suzi       |
+| NULL       |
 +------------+
 ```
 
@@ -107,4 +131,4 @@ SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Hen
 | Henry      |
 | Henry      |
 +------------+
-```
+```

i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/other-functions/field.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "FIELD",
     "language": "zh-CN",
@@ -9,14 +9,14 @@
 ## 描述
 
 返回 `<expr>` 在参数列表中的位置（基于 1 的索引），常用于 `ORDER BY` 子句中实现自定义排序。如果 `<expr>` 不在参数列表中，或 `<expr>` 为 `NULL`，则返回 `0`。在自定义排序中，不在参数列表中的数据会被排到最前面，可通过 `asc` 或 `desc` 控制整体排序顺序；对于 `NULL` 值，可以使用 `nulls first` 或 `nulls last` 控制排序顺序。
 
 ## 语法
 
 ```sql
 FIELD(<expr>, <param> [, ...])
 ```
 
 ## 参数
 
 | 参数       | 说明                  |
 |------------|-----------------------|
@@ -29,6 +29,42 @@
 
 ## 举例
 
+```sql
+-- setup
+CREATE TABLE baseall (k1 INT, k7 VARCHAR(64))
+DISTRIBUTED BY HASH(k1) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO baseall VALUES
+    (1, 'wangjing04'),
+    (2, 'wangyu14'),
+    (3, 'yuanyuan06');
+
+CREATE TABLE class_test (class_name VARCHAR(64))
+DISTRIBUTED BY HASH(class_name) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO class_test VALUES
+    ('Suzi'), ('Suzi'),
+    ('Ben'), ('Ben'),
+    ('Henry'), ('Henry'),
+    (NULL);
+```
+
+直接使用 `FIELD` 查找位置（基于 1 的索引）：
+
+```sql
+SELECT FIELD(2, 3, 1, 2, 5);
+```
+
+```text
++----------------------+
+| FIELD(2, 3, 1, 2, 5) |
++----------------------+
+|                    3 |
++----------------------+
+```
+
 ```sql
 SELECT k1, k7 FROM baseall WHERE k1 IN (1,2,3) ORDER BY FIELD(k1,2,1,3);
 ```
@@ -51,6 +87,7 @@
 +------------+
 | class_name |
 +------------+
+| NULL       |
 | Suzi       |
 | Suzi       |
 | Ben        |
@@ -74,6 +111,7 @@
 | Ben        |
 | Suzi       |
 | Suzi       |
+| NULL       |
 +------------+
 ```
 
@@ -93,4 +131,4 @@
 | Henry      |
 | Henry      |
 +------------+
-```
+```

i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/other-functions/field.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "FIELD",
     "language": "zh-CN",
@@ -9,14 +9,14 @@
 ## 描述
 
 返回 `<expr>` 在参数列表中的位置（基于 1 的索引），常用于 `ORDER BY` 子句中实现自定义排序。如果 `<expr>` 不在参数列表中，或 `<expr>` 为 `NULL`，则返回 `0`。在自定义排序中，不在参数列表中的数据会被排到最前面，可通过 `asc` 或 `desc` 控制整体排序顺序；对于 `NULL` 值，可以使用 `nulls first` 或 `nulls last` 控制排序顺序。
 
 ## 语法
 
 ```sql
 FIELD(<expr>, <param> [, ...])
 ```
 
 ## 参数
 
 | 参数       | 说明                  |
 |------------|-----------------------|
@@ -29,6 +29,42 @@
 
 ## 举例
 
+```sql
+-- setup
+CREATE TABLE baseall (k1 INT, k7 VARCHAR(64))
+DISTRIBUTED BY HASH(k1) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO baseall VALUES
+    (1, 'wangjing04'),
+    (2, 'wangyu14'),
+    (3, 'yuanyuan06');
+
+CREATE TABLE class_test (class_name VARCHAR(64))
+DISTRIBUTED BY HASH(class_name) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO class_test VALUES
+    ('Suzi'), ('Suzi'),
+    ('Ben'), ('Ben'),
+    ('Henry'), ('Henry'),
+    (NULL);
+```
+
+直接使用 `FIELD` 查找位置（基于 1 的索引）：
+
+```sql
+SELECT FIELD(2, 3, 1, 2, 5);
+```
+
+```text
++----------------------+
+| FIELD(2, 3, 1, 2, 5) |
++----------------------+
+|                    3 |
++----------------------+
+```
+
 ```sql
 SELECT k1, k7 FROM baseall WHERE k1 IN (1,2,3) ORDER BY FIELD(k1,2,1,3);
 ```
@@ -51,6 +87,7 @@
 +------------+
 | class_name |
 +------------+
+| NULL       |
 | Suzi       |
 | Suzi       |
 | Ben        |
@@ -74,6 +111,7 @@
 | Ben        |
 | Suzi       |
 | Suzi       |
+| NULL       |
 +------------+
 ```
 
@@ -93,4 +131,4 @@
 | Henry      |
 | Henry      |
 +------------+
-```
+```

versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/other-functions/field.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "FIELD",
     "language": "en",
@@ -17,7 +17,7 @@
 FIELD(<expr>, <param> [, ...])
 ```
 
 ## Parameters
 
 | Parameter  | Description                                             |
 |------------|---------------------------------------------------------|
@@ -25,13 +25,35 @@
 | `<param>`  | A sequence of values to compare against `<expr>`.       |
 
 ## Return Value
 
 - Returns the position (1-based index) of `<expr>` in the list of `<param>` values.  
 - If `<expr>` is not found, returns `0`.  
 - If `<expr>` is `NULL`, returns `0`.
 
 ## Examples
 
+```sql
+-- setup
+CREATE TABLE baseall (k1 INT, k7 VARCHAR(64))
+DISTRIBUTED BY HASH(k1) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO baseall VALUES
+    (1, 'wangjing04'),
+    (2, 'wangyu14'),
+    (3, 'yuanyuan06');
+
+CREATE TABLE class_test (class_name VARCHAR(64))
+DISTRIBUTED BY HASH(class_name) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO class_test VALUES
+    ('Suzi'), ('Suzi'),
+    ('Ben'), ('Ben'),
+    ('Henry'), ('Henry'),
+    (NULL);
+```
+
 ```sql
 SELECT FIELD(2, 3, 1, 2, 5);
 ```
@@ -58,6 +80,8 @@
 +------+------------+
 ```
 
+Custom string ordering. `FIELD` returns `0` for values not in the list — including `NULL`, which is why the `NULL` row sorts to the top in the ascending default:
+
 ```sql
 SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry');
 ```
@@ -66,11 +90,52 @@
 +------------+
 | class_name |
 +------------+
+| NULL       |
+| Suzi       |
+| Suzi       |
+| Ben        |
+| Ben        |
+| Henry      |
+| Henry      |
++------------+
+```
+
+Descending — `NULL` (FIELD = 0) is now last:
+
+```sql
+SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry') DESC;
+```
+
+```text
++------------+
+| class_name |
++------------+
+| Henry      |
+| Henry      |
+| Ben        |
+| Ben        |
+| Suzi       |
+| Suzi       |
+| NULL       |
++------------+
+```
+
+You can also use `NULLS FIRST` / `NULLS LAST` to control `NULL` placement independently of the sort direction:
+
+```sql
+SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry') NULLS FIRST;
+```
+
+```text
++------------+
+| class_name |
++------------+
+| NULL       |
 | Suzi       |
 | Suzi       |
 | Ben        |
 | Ben        |
 | Henry      |
 | Henry      |
 +------------+
-```
+```

versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/other-functions/field.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "FIELD",
     "language": "en",
@@ -17,7 +17,7 @@
 FIELD(<expr>, <param> [, ...])
 ```
 
 ## Parameters
 
 | Parameter  | Description                                             |
 |------------|---------------------------------------------------------|
@@ -32,6 +32,28 @@
 
 ## Examples
 
+```sql
+-- setup
+CREATE TABLE baseall (k1 INT, k7 VARCHAR(64))
+DISTRIBUTED BY HASH(k1) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO baseall VALUES
+    (1, 'wangjing04'),
+    (2, 'wangyu14'),
+    (3, 'yuanyuan06');
+
+CREATE TABLE class_test (class_name VARCHAR(64))
+DISTRIBUTED BY HASH(class_name) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO class_test VALUES
+    ('Suzi'), ('Suzi'),
+    ('Ben'), ('Ben'),
+    ('Henry'), ('Henry'),
+    (NULL);
+```
+
 ```sql
 SELECT FIELD(2, 3, 1, 2, 5);
 ```
@@ -58,6 +80,8 @@
 +------+------------+
 ```
 
+Custom string ordering. `FIELD` returns `0` for values not in the list — including `NULL`, which is why the `NULL` row sorts to the top in the ascending default:
+
 ```sql
 SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry');
 ```
@@ -66,11 +90,52 @@
 +------------+
 | class_name |
 +------------+
+| NULL       |
+| Suzi       |
+| Suzi       |
+| Ben        |
+| Ben        |
+| Henry      |
+| Henry      |
++------------+
+```
+
+Descending — `NULL` (FIELD = 0) is now last:
+
+```sql
+SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry') DESC;
+```
+
+```text
++------------+
+| class_name |
++------------+
+| Henry      |
+| Henry      |
+| Ben        |
+| Ben        |
+| Suzi       |
+| Suzi       |
+| NULL       |
++------------+
+```
+
+You can also use `NULLS FIRST` / `NULLS LAST` to control `NULL` placement independently of the sort direction:
+
+```sql
+SELECT class_name FROM class_test ORDER BY FIELD(class_name, 'Suzi', 'Ben', 'Henry') NULLS FIRST;
+```
+
+```text
++------------+
+| class_name |
++------------+
+| NULL       |
 | Suzi       |
 | Suzi       |
 | Ben        |
 | Ben        |
 | Henry      |
 | Henry      |
 +------------+
-```
+```