Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add more desc about sync select #3355

Merged
merged 2 commits into from
Jul 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/zh/openmldb_sql/ddl/SET_STATEMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,19 +148,20 @@ CREATE TABLE t1 (col0 STRING, col1 int, std_time TIMESTAMP, INDEX(KEY=col1, TS=s

### 离线命令配置详情

- 设置离线命令同步执行,同步的超时时间将自动设置为gflag `sync_job_timeout`,默认30min
- 设置离线命令同步执行,同步的超时时间将自动设置为30min(gflag `sync_job_timeout`,同时也是与TaskManager的最大超时时间,仅手动设置更大的此超时时间是无意义的)

```sql
> SET @@sync_job = "true";
```

```{caution}
如果离线同步命令执行时间超过30min(同步命令超时时间默认值),需要同时调整TaskManager配置和客户端的配置。
如果离线同步命令执行时间超过30min,需要同时调整TaskManager配置和客户端的配置。
- 调大TaskManager的`server.channel_keep_alive_time`
- 配置客户端`--sync_job_timeout`,不可大于`server.channel_keep_alive_time`。SDK暂不支持修改。
```

- 离线命令异步执行时,同样会有超时时间,可手动配置。设置离线异步命令或离线管理命令的等待时间(单位为毫秒):
- 设置离线异步命令或离线管理命令的等待时间,单位为毫秒,默认为1min:

```sql
> SET @@job_timeout = "600000";
```
Expand Down
11 changes: 11 additions & 0 deletions docs/zh/quickstart/function_boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,3 +154,14 @@ OpenMLDB CLI 中在线模式下执行 SQL,均为在线预览模式。在线预

两种模式虽然不同,但使用的是相同的 SQL 语句,且计算结果一致。但由于离线和在线使用两套执行引擎,功能尚未完全对齐,因此离线可执行的 SQL 不一定可以部署上线(在线请求模式可执行的 SQL 是离线可执行 SQL 的子集)。在实际开发中,需要在完成离线 SQL 开发后 `DEPLOY`,来测试 SQL 是否可上线。

## 离线命令同步模式

所有离线命令都可以通过`set @@sync_job=true;`来设置同步模式,同步模式下,命令执行完毕后才会返回,否则会立即返回离线Job的Job info,需要通过`SHOW JOB <id>`来查询Job的执行状态。而同步模式下的返回值会根据命令的不同而不同:

- DML,例如`LOAD DATA`等,以及DQL `SELECT INTO`,返回的是Job Info的ResultSet。它们和异步模式的结果没有区别,只是返回时间的区别,Job Info的ResultSet也可解析。

- DQL的普通`SELECT`,在异步模式中返回Job Info,同步模式中则是返回查询结果,但目前支持不完善,详细解释见[离线同步模式-select](../openmldb_sql/dql/SELECT_STATEMENT.md#离线同步模式-select)。其结果为csv格式,但不保证数据完整性,不建议将其作为可靠的查询结果使用。
- CLI是交互模式,所以将结果直接打印。
- SDK中,返回的是一行一列的ResultSet,将整个查询结果作为一个字符串返回。所以,不建议SDK使用同步模式查询,并处理其结果。

同步模式涉及超时问题,详情见[调整配置](../../openmldb_sql/ddl/SET_STATEMENT.md#离线命令配置详情)。
6 changes: 5 additions & 1 deletion docs/zh/quickstart/openmldb_quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,11 @@ LOAD DATA INFILE 'file:///work/taxi-trip/data/data.parquet' INTO TABLE demo_tabl
这里使用 `SHOW JOBS` 查看任务状态,请等待任务运行成功( `state` 转至 `FINISHED` 状态),再进行下面步骤。
![image-20220111141358808](./images/state_finished.png)

任务完成以后,如果希望预览数据,可以使用 `SELECT * FROM demo_table1` 语句,推荐先将离线命令设置为同步模式(`SET @@sync_job=true`);否则该命令会提交一个异步任务,结果会保存在 Spark 任务的日志文件中,查看较不方便。
任务完成以后,如果希望预览数据,可以在同步模式`SET @@sync_job=true`下 `SELECT * FROM demo_table1` 语句。但它有一定的限制,详情见[离线命令同步模式](./function_boundary.md#离线命令同步模式)。

默认的异步模式下,`SELECT * FROM demo_table1`会提交一个异步任务,结果会保存在 Spark 任务的日志文件中,查看较不方便。如果TaskManager为local,可以`SHOW JOBLOG <id>`查看stdout中的查询打印结果。

最可靠的方式是,可以使用 `SELECT INTO` 命令,将数据导出到指定目录,或直接查看导入后的存储地址。

```{note}
OpenMLDB 也支持链接形式的软拷贝来导入离线数据,无需数据硬拷贝。可以参考 [LOAD DATA INFILE 文档](../openmldb_sql/dml/LOAD_DATA_STATEMENT.md) 的参数 `deep_copy` 的说明。
Expand Down
8 changes: 2 additions & 6 deletions docs/zh/quickstart/sdk/java_sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,9 @@ res = stmt.executeQuery("SELECT * from t1"); // 在线 select, executeQuery 可

其中,`LOAD DATA` 命令是异步命令,返回的 ResultSet 包含该 job 的 id、state 等信息。可通过执行 `show job <id>` 来查询 job 是否执行完成。注意 ResultSet 需要先执行 `next()` 游标才会指向第一行数据。

也可以改为同步命令:
离线模式默认为异步执行,返回的ResultSet是Job Info,可以通过`SET @@sync_job=true;`改为同步执行,但返回的ResultSet根据SQL不同,详情见[功能边界-离线命令同步模式](../function_boundary.md#离线命令同步模式)。只推荐在`LOAD DATA`/`SELECT INTO`时选择同步执行。

```SQL
SET @@sync_job=true;
```

如果同步命令实际耗时超过连接空闲默认的最大等待时间 0.5 小时,请[调整配置](../../openmldb_sql/ddl/SET_STATEMENT.md#离线命令配置详情)。
如果同步命令超时,请参考[离线命令配置详情](../../openmldb_sql/ddl/SET_STATEMENT.md#离线命令配置详情)调整配置。

```{caution}
`Statement`执行`SET @@execute_mode='offline'`不仅会影响当前`Statement`,还会影响该`Connection`已创建和未创建的所有`Statement`。所以,不建议创建多个`Statement`,并期望它们在不同的模式下执行。如果需要在不同模式下执行SQL,建议创建多个Connection。
Expand Down