From 7a6ab4a5be6f134c2564965f95966289732e91c4 Mon Sep 17 00:00:00 2001 From: aceforeverd Date: Fri, 8 Dec 2023 22:51:20 +0800 Subject: [PATCH] docs(sql): update sql supports - add set operation --- .../ONLINE_REQUEST_REQUIREMENTS.md | 1 + docs/zh/openmldb_sql/dql/JOIN_CLAUSE.md | 2 +- docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md | 50 ++++++++++------- docs/zh/openmldb_sql/dql/SET_OPERATION.md | 53 +++++++++++++++++++ docs/zh/openmldb_sql/dql/index.rst | 1 + docs/zh/openmldb_sql/index.rst | 4 +- docs/zh/openmldb_sql/sql_difference.md | 23 ++++---- 7 files changed, 100 insertions(+), 34 deletions(-) create mode 100644 docs/zh/openmldb_sql/dql/SET_OPERATION.md diff --git a/docs/zh/openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md b/docs/zh/openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md index 7a4a8501490..1bf5ac50f94 100644 --- 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 index 64058ab1917..00324c83af8 100644 --- 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 index d846d567ef3..01b34828382 100644 --- 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 new file mode 100644 index 00000000000..972ada1ffa0 --- /dev/null +++ b/docs/zh/openmldb_sql/dql/SET_OPERATION.md @@ -0,0 +1,53 @@ +# SET Operation + + + +SET 操作将两个或者更多相同输出 schema 的 query 语句按特定的规则整合成一个结果输出. 共有三种 Set 操作符: `UNION`, `INTERSEC`, `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 index 07baf688985..7a10c319e04 100644 --- 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 index 149147f1f55..883425443d5 100644 --- 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 diff --git a/docs/zh/openmldb_sql/sql_difference.md b/docs/zh/openmldb_sql/sql_difference.md index 0b521dd2eca..b224db6d567 100644 --- a/docs/zh/openmldb_sql/sql_difference.md +++ b/docs/zh/openmldb_sql/sql_difference.md @@ -1,26 +1,26 @@ # 与标准 SQL 的主要差异 -本文将 OpenMLDB SQL 的主要使用方式（SELECT 查询语句）与标准 SQL （以 MySQL 支持的语法为例）进行比较，让有 SQL 使用经验的开发者快速上手 OpenMLDB SQL。 +本文将 OpenMLDB SQL 的主要使用方式（Query 查询语句）与标准 SQL （以 MySQL 支持的语法为例）进行比较，让有 SQL 使用经验的开发者快速上手 OpenMLDB SQL。 以下如无特殊说明，默认均为 OpenMLDB 版本：>= v0.7.1 ## 支持总览 -下表根据 SELECT 语句元素对 OpenMLDB SQL 在三种执行模式下（关于执行模式参考[使用流程和执行模式](../quickstart/concepts/modes.md)）与标准 SQL 整体性的差异做了汇总。OpenMLDB SQL 目前部分兼容标准 SQL，但考虑实际业务场景需求新增了部分语法，下表加粗部分为新增语法。 +下表根据 Query语句元素对 OpenMLDB SQL 在三种执行模式下（关于执行模式参考[使用流程和执行模式](../quickstart/concepts/modes.md)）与标准 SQL 整体性的差异做了汇总。OpenMLDB SQL 目前部分兼容标准 SQL，但考虑实际业务场景需求新增了部分语法，下表加粗部分为 OpenMLDB SQL 特有语法。 注：✓ 表示**支持**该语句，✕ 表示**不支持**。 | | **OpenMLDB SQL**
**离线模式** | **OpenMLDB SQL**
**在线预览模式** | **OpenMLDB SQL**
**在线请求模式** | **标准 SQL** | **备注** | | -------------- | ---------------------------- | -------------------------------- | -------------------------------- | ------------ | ------------------------------------------------------------ | +| JOIN Operation | ✓ | ✕ | ✓ | ✓ | OpenMLDB 支持特有的 **LAST JOIN**, 和 LEFT JOIN | +| SET Operation | ✓ | ✓ | ✓ | ✓ | OpenMLDB 仅支持 UNION | | WHERE 子句 | ✓ | ✓ | ✕ | ✓ | 部分功能可以通过带有 `_where` 后缀的内置函数实现 | -| HAVING 子句 | ✓ | ✓ | X | ✓ | | -| JOIN 子句 | ✓ | ✕ | ✓ | ✓ | OpenMLDB 支持特有的 **LAST JOIN**, 和 **LEFT JOIN** | -| GROUP BY 分组 | ✓ | ✕ | ✕ | ✓ | | -| ORDER BY 关键字 | ✓ | ✓ | ✓ | ✓ | 仅支持在 `WINDOW` 和 `LAST JOIN` 子句内部使用，不支持倒排序 `DESC` | -| LIMIT 限制行数 | ✓ | ✓ | ✕ | ✓ | | +| GROUP BY / HAVING 分组 | ✓ | ✓ | ✕ | ✓ | OpenMLDB >= 0.6.4 支持 GROUP BY, HAVING | | WINDOW 子句 | ✓ | ✓ | ✓ | ✓ | OpenMLDB 增加了特有的 **WINDOW ... UNION** 和 **WINDOW ATTRIBUTES** 语法 | -| WITH 子句 | ✕ | ✕ | ✕ | ✓ | OpenMLDB 从版本 v0.7.2 开始支持 | -| 聚合函数 | ✓ | ✓ | ✓ | ✓ | OpenMLDB 有较多扩展函数 | +| ORDER BY 关键字 (不是 SELECT 里的 ORDER BY 子句) | ✓ | ✓ | ✓ | ✓ | 仅支持在 `WINDOW` 和 **`LAST JOIN`** 子句内部使用，不支持倒排序 `DESC` | +| LIMIT 限制行数 | ✓ | ✓ | ✕ | ✓ | | +| WITH 子句 | ✓ | ✓ | ✓ | ✓ | OpenMLDB 从版本 v0.7.2 开始支持 | +| 聚合函数 | ✓ | ✓ | ✓ | ✓ | OpenMLDB 有自己的[拓展函数](https://openmldb.ai/docs/zh/main/openmldb_sql/udfs_8h.html), 部分兼容其他 SQL | @@ -104,8 +104,9 @@ OpenMLDB 支持 LAST JOIN 和 LEFT JOIN，详细描述参考扩展语法的 JOIN | LAST JOIN + 左右表均为简单列筛选 | ✓ | ✕ | ✓l | | LAST JOIN + 右表是带 WHERE 条件过滤的单表查询 | ✓ | ✕ | ✓ | | LAST JOIN左表或右表为 WINDOW 或 LAST JOIN 操作 | ✓ | ✕ | ✓ | -| LAST JOIN + 右表是LEFT JOIN 的子查询 | ✕ | ✕ | ✓ | -| LEFT JOIN | ✕ | ✕ | ✕ | +| LAST JOIN + 右表是LEFT JOIN 的子查询 | ✓ | ✕ | ✓ | +| LAST JOIN + 右表是 UNION ALL 子查询 | ✓ | ✓ | ✓ | +| LEFT JOIN | ✓ | ✕ | ✕ | 特殊限制：