docs(sql): update sql supports (#3672)

- add set operation
4paradigm · Dec 14, 2023 · fa91a98 · fa91a98
1 parent 0c2592d
commit fa91a98
Show file tree

Hide file tree

Showing 7 changed files with 100 additions and 34 deletions.
diff --git a/docs/zh/openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md b/docs/zh/openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md
@@ -70,6 +70,7 @@ SELECT substr(COL7, 3, 6) FROM t1;
     - **OpenMLDB >= 0.8.0** 带 WHERE 条件过滤的简单列筛选 ( 例如 `select * from tb where id > 10`)
     - **[ALPHA] OpenMLDB >= 0.8.4** 右表是带 LAST JOIN 的子查询 `subquery`, 要求 `subquery` 最左的表能被 JOIN 条件优化, `subquery`剩余表能被自身 LAST JOIN 的 JOIN 条件优化 
     - **[ALPHA] OpenMLDB >= 0.8.4** LEFT JOIN. 要求 LEFT JOIN 的右表能被 LEFT JOIN 条件优化, LEFT JOIN 的左表能被上层的 LAST JOIN 条件优化
+    - **[ALPHA] OpenMLDB >= 0.8.5** UNION ALL query. 要求 UNION ALL 内的每一个 query 都可以被 LAST JOIN 的条件优化
 
 **Example: 支持上线的 `LAST JOIN` 语句范例**
 创建两张表以供后续`LAST JOIN`。

diff --git a/docs/zh/openmldb_sql/dql/JOIN_CLAUSE.md b/docs/zh/openmldb_sql/dql/JOIN_CLAUSE.md
@@ -48,7 +48,7 @@ SELECT ... FROM t1 LEFT JOIN t2 ON expression;
 | SELECT语句元素                                 | 离线模式  | 在线预览模式 | 在线请求模式 | 说明                                                                                                                                                                                                 |
 | :--------------------------------------------- | --------- | ------------ | ------------ |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | LAST JOIN | **``✓``** | **``x``** | **``✓``** | 表示数据来源多个表JOIN。在线请求模式下，需要遵循[在线请求模式下LAST JOIN的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下-last-join-的使用规范)                                        |
-| LEFT JOIN | **``x``** | **``x``** | **``✓``** | 由于 LEFT JOIN 是一对多 JOIN, 本身不能直接用于在线请求模式. 但是可以作为其他类型查询内部的子查询, 例如作为 LAST JOIN 的右表. 具体参考[在线请求模式下LAST JOIN的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下-last-join-的使用规范) |
+| LEFT JOIN | **``✓``** | **``x``** | **``✓``** | 由于 LEFT JOIN 是一对多 JOIN, 本身不能直接用于在线请求模式. 但是可以作为其他类型查询内部的子查询, 例如作为 LAST JOIN 的右表. 具体参考[在线请求模式下LAST JOIN的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下-last-join-的使用规范) |
 
 
 ### 未排序的LAST JOIN 

diff --git a/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md b/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md
@@ -1,8 +1,6 @@
-# SELECT 概况
+# Query 语句
 
-## Syntax
-
-### Syntax Notation
+## Syntax Notation
 
 - `[ expr ]`: 中括号，可选部分
 - `{}`: 手动分组
@@ -11,7 +9,7 @@
 - 大写变量，例如 `WITH`, 表示 SQL 关键词 "WITH"
 - 小写变量, 例如 `query`, 可以拓展成特定语法结构
 
-### Select Statement
+## Syntax
 
 ```yacc
 query_statement:
@@ -38,7 +36,7 @@ non_recursive_cte:
   cte_name AS ( query )
 
 set_operator:
-  UNION ALL
+  UNION { ALL | DISTINCT }
 
 from_item:
   table_name [ as_alias ]
@@ -100,19 +98,21 @@ select_expression:
   expression [ [ AS ] alias ]
 ```
 
-## SELECT语句元素
+## Query 语句元素
 
 | SELECT语句元素                                     | 离线模式  | 在线预览模式 | 在线请求模式 | 说明                                                                                                                                                                                                                        |
 |:-----------------------------------------------| --------- | ------------ | ------------ |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [`SELECT` Clause](#selectexprlist)     | **``✓``** | **``✓``**    | **``✓``**    | 投影操作列表，一般包括列名、表达式，或者是用 `*` 表示全部列                                                                                                                                                                                          |
-| [`FROM` Clause](#tablerefs)                 | **``✓``** | **``✓``**    | **``✓``**    | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 LAST JOIN (见[JOIN 子句](../dql/JOIN_CLAUSE.md)) 或者是0个表 ( `select 1+1;`)，详见[NO_TABLE SELECT](../dql/NO_TABLE_SELECT_CLAUSE.md)                                                   |
-| [`JOIN` Clause](../dql/JOIN_CLAUSE.md)         | **``✓``** | **``x``**    | **``✓``**    | 表示数据来源多个表JOIN。OpenMLDB目前仅支持LAST JOIN。在线请求模式下，需要遵循[Online Request下LAST JOIN的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下-last-join-的使用规范)                                                       |
-| [`WHERE` Clause](../dql/WHERE_CLAUSE.md)       |          | **``✓``**    |              | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据。                                                                                                                                                                                        |
-| [`GROUP BY` Clause](../dql/GROUP_BY_CLAUSE.md) | **``✓``** |  **``✓``**   |              | Group By 子句用于对查询结果集进行分组。分组表达式列表仅支持简单列。                                                                                                                                                                                    |
-| [`HAVING` Clause](../dql/HAVING_CLAUSE.md)     | **``✓``** |  **``✓``**   |              | Having 子句与 Where 子句作用类似.Having 子句过滤 GroupBy 后的各种数据，Where 子句在聚合前进行过滤。                                                                                                                                                      |
+| [`WITH` Clause](./WITH_CLAUSE.md) | **``✓``** | **``✓``**    | **``✓``**    |                                                                                                                                                                                           |
+| [`SELECT` list](#selectexprlist) | **``✓``** | **``✓``**    | **``✓``**    | 投影操作列表，一般包括列名、表达式，或者是用 `*` 表示全部列                                                                                                                                                                                          |
+| [`FROM` Clause](#from-clause)      | **``✓``** | **``✓``**    | **``✓``**    | 表示数据来源                                                   |
+| [`JOIN` Operation](../dql/JOIN_CLAUSE.md) | **``✓``** | **``x``**    | **``✓``**    | 表示数据来源多个表JOIN。OpenMLDB目前仅支持LAST JOIN。在线请求模式下，需要遵循[Online Request下LAST JOIN的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下-last-join-的使用规范)                                                       |
+| [`SET` Operation](./SET_OPERATION.md) | **``✓``** | **``✓``** | **``✓``** | 只支持 UNION, 在线支持 UNION ALL, 离线支持 UNION ALL/DISTINCT |
+| [`WHERE` Clause](../dql/WHERE_CLAUSE.md)       | **``x``** | **``✓``**    | **``x``** | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据。                                                                                                                                                                                        |
+| [`GROUP BY` Clause](../dql/GROUP_BY_CLAUSE.md) | **``✓``** |  **``✓``**   | **``x``** | Group By 子句用于对查询结果集进行分组。分组表达式列表仅支持简单列。                                                                                                                                                                                    |
+| [`HAVING` Clause](../dql/HAVING_CLAUSE.md)     | **``✓``** |  **``✓``**   | **``x``** | Having 子句与 Where 子句作用类似.Having 子句过滤 GroupBy 后的各种数据，Where 子句在聚合前进行过滤。                                                                                                                                                      |
 | [`WINDOW` Clause](../dql/WINDOW_CLAUSE.md)     | **``✓``** |  **``✓``**   | **``✓``**    | 窗口子句用于定义一个或者若干个窗口。窗口可以是有名或者匿名的。用户可以在窗口上调用聚合函数来进行一些分析型计算的操作（```sql agg_func() over window_name```)。线请求模式下，需要遵循[Online Request下Window的使用规范](../deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#在线请求模式下window的使用规范) |
-| [`LIMIT` Clause](../dql/LIMIT_CLAUSE.md)       | **``✓``** | **``✓``**    |              | Limit子句用于限制返回的结果条数。目前Limit仅支持接受一个参数，表示返回数据的最大行数。                                                                                                                                                                          |
-| `ORDER BY` Clause                              |           |              |              | 标准SQL还支持Order By子句。OpenMLDB目前尚未支持Order子句。例如，查询语句`SELECT * from t1 ORDER BY col1;`在OpenMLDB中不被支持。                                                                                                                          |
+| [`LIMIT` Clause](../dql/LIMIT_CLAUSE.md)       | **``✓``** | **``✓``**    | **``x``** | Limit子句用于限制返回的结果条数。目前Limit仅支持接受一个参数，表示返回数据的最大行数。                                                                                                                                                                          |
+| `ORDER BY` Clause                              | **``x``** | **``x``** | **``x``** | 标准SQL还支持Order By子句。OpenMLDB目前尚未支持Order子句。例如，查询语句`SELECT * from t1 ORDER BY col1;`在OpenMLDB中不被支持。                                                                                                                          |
 
 ```{warning}
 在线模式或单机版的select，可能无法获取完整数据。
@@ -123,18 +123,28 @@ select_expression:
 在线模式或单机版都不适合做大数据的扫描，推荐使用集群版的离线模式。如果一定要调大扫描量，需要对每台tablet配置`--scan_max_bytes_size=xxx`，并重启tablet生效。
 ```
 
-## 离线同步模式 SELECT
+## FROM Clause
+
+FROM子句指定了查询的原始数据来源,即我们要在哪些表中查找所需的数据。它也会定义这些数据源间的联系,比如是否通过某些字段建立连接查询,从而将原本分散在多个表中的数据整合在一起,形成一个单一的数据集以供查询操作使用. 
+
+FROM 子句的来源可以是:
+
+- 表名或者 Common Table Expression (CTE), 同名情况下 CTE 优先级更高
+- JOIN 操作, OpenMLDB 支持 LEFT JOIN 和 LAST JOIN
+- 任意子查询, 被括在括号中
+
+## 离线同步模式 Query
 
-设置`SET @@sync_job=true`后的`SELECT`语句，就是离线同步模式下的`SELECT`。在这个状态下的`SELECT`会展示结果到CLI（不建议在SDK中使用这种模式，不会得到正常的ResultSet）。
+设置`SET @@sync_job=true`后的 Query 语句，就是离线同步模式下的 Query。在这个状态下的 Query 会展示结果到CLI（不建议在SDK中使用这种模式，不会得到正常的ResultSet）。
 
-原理：SELECT执行完成后各worker通过HTTP发送结果到TaskManager，TaskManager收集各个结果分片并保存到本地文件系统中。结果收集完成后，再从本地文件系统读取，读取后删除本地缓存的结果。
+原理：Query 执行完成后各worker通过HTTP发送结果到TaskManager，TaskManager收集各个结果分片并保存到本地文件系统中。结果收集完成后，再从本地文件系统读取，读取后删除本地缓存的结果。
 
 ```{attention}
-离线同步模式 SELECT 仅用于展示，不保证结果完整。整个结果收集中可能出现文件写入失败，丢失HTTP包等问题，我们允许结果缺失。
+离线同步模式 Query 仅用于展示，不保证结果完整。整个结果收集中可能出现文件写入失败，丢失HTTP包等问题，我们允许结果缺失。
 ```
 ### 相关配置参数
 
-TaskManager配置`batch.job.result.max.wait.time`，在`SELECT` job完成后，我们会等待所有结果被收集并保存在TaskManager所在主机的文件系统中，超过这一时间将结束等待，返回错误。如果认为整个收集结果的过程没有问题，仅仅是等待时间不够，可以调大这一配置项，单位为ms，默认为10min。
+TaskManager配置`batch.job.result.max.wait.time`，在 Query job完成后，我们会等待所有结果被收集并保存在TaskManager所在主机的文件系统中，超过这一时间将结束等待，返回错误。如果认为整个收集结果的过程没有问题，仅仅是等待时间不够，可以调大这一配置项，单位为ms，默认为10min。
 
 Batch配置(spark.default.conf):
 - spark.openmldb.savejobresult.rowperpost: 为了防止HTTP传送过多数据，我们对数据进行切割，默认为16000行。如果单行数据量较大，可以调小该值。

diff --git a/docs/zh/openmldb_sql/dql/SET_OPERATION.md b/docs/zh/openmldb_sql/dql/SET_OPERATION.md
@@ -0,0 +1,53 @@
+# SET Operation
+
+
+
+SET 操作将两个或者更多相同输出 schema 的 query 语句按特定的规则整合成一个结果输出. 共有三种 Set 操作符: `UNION`, `INTERSECT`, `EXCEPT`, OpenMLDB 目前仅支持 `UNION`.
+
+
+
+## Syntax
+
+```yacc
+set_operation:
+  query set_operator query
+
+set_operator:
+  UNION { ALL | DISTINCT }
+```
+
+注意
+
+- `ALL/DISTINCT` 是必填, 不支持单独 UNION 的写法
+- 同一层 Set Operation 里, 多个 UNION 操作必须都是 UNION ALL 或者 UNION DISTINCT.  可以利用子查询将不同 DISTINCT 属性的 query 串联起来
+- 这里的 UNION 语法不同于 [WINDOW clause](./WINDOW_CLAUSE.md) 中的 WINDOW UNION 语法 
+
+## 边界说明
+
+| SELECT语句元素 | 离线模式  | 在线预览模式 | 在线请求模式 | 说明 |
+| :------------- | --------- | ------------ | ------------ | :--- |
+| SET Operation  | **``✓``** | **``✓``**    | **``✓``**    |      |
+
+- 在线模式下只支持 UNION ALL, 离线模式支持 UNION ALL 和 UNION DISTINCT
+
+
+
+## Example
+
+```sql
+SELECT * FROM t1
+UNION ALL
+SELECT * FROM t2
+UNION ALL
+SELECT * FROM t3
+
+-- differnt DISTINCT field
+SELECT * FROM t1
+UNION ALL
+(
+    SELECT * FROM t2
+    UNION DISTINCT
+    SELECT * FROM t3
+)
+```
+
diff --git a/docs/zh/openmldb_sql/dql/index.rst b/docs/zh/openmldb_sql/dql/index.rst
@@ -8,6 +8,7 @@
 
     SELECT_STATEMENT
     JOIN_CLAUSE
+    SET_OPERATION
     WHERE_CLAUSE
     GROUP_BY_CLAUSE
     HAVING_CLAUSE

diff --git a/docs/zh/openmldb_sql/index.rst b/docs/zh/openmldb_sql/index.rst
@@ -5,9 +5,9 @@ OpenMLDB SQL
 
 .. toctree::
     :maxdepth: 1
-    
+
     sql_difference
-    language_structure/index 
+    language_structure/index
     data_types/index
     functions_and_operators/index
     udfs_8h