From a006bc9c7721ff6719f7c7d898d28ce6da23d380 Mon Sep 17 00:00:00 2001 From: Huang Wei Date: Wed, 12 Jul 2023 11:57:09 +0800 Subject: [PATCH] docs: add more desc about sync select --- docs/zh/openmldb_sql/ddl/SET_STATEMENT.md | 6 +++--- docs/zh/quickstart/function_boundary.md | 11 +++++++++++ docs/zh/quickstart/openmldb_quickstart.md | 6 +++++- docs/zh/quickstart/sdk/java_sdk.md | 8 ++------ 4 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/zh/openmldb_sql/ddl/SET_STATEMENT.md b/docs/zh/openmldb_sql/ddl/SET_STATEMENT.md index cf14540f7b0..b36627d05bc 100644 --- a/docs/zh/openmldb_sql/ddl/SET_STATEMENT.md +++ b/docs/zh/openmldb_sql/ddl/SET_STATEMENT.md @@ -148,19 +148,19 @@ CREATE TABLE t1 (col0 STRING, col1 int, std_time TIMESTAMP, INDEX(KEY=col1, TS=s ### 离线命令配置详情 -- 设置离线命令同步执行，同步的超时时间将自动设置： +- 设置离线命令同步执行，同步的超时时间将自动设置为30min（同时也是与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"; ``` diff --git a/docs/zh/quickstart/function_boundary.md b/docs/zh/quickstart/function_boundary.md index 9162534982f..601e80d23f5 100644 --- a/docs/zh/quickstart/function_boundary.md +++ b/docs/zh/quickstart/function_boundary.md @@ -144,3 +144,14 @@ OpenMLDB CLI 中在线模式下执行 SQL，均为在线预览模式。在线预 两种模式虽然不同，但使用的是相同的 SQL 语句，且计算结果一致。但由于离线和在线使用两套执行引擎，功能尚未完全对齐，因此离线可执行的 SQL 不一定可以部署上线（在线请求模式可执行的 SQL 是离线可执行 SQL 的子集）。在实际开发中，需要在完成离线 SQL 开发后 `DEPLOY`，来测试 SQL 是否可上线。 +## 离线命令同步模式 + +所有离线命令都可以通过`set @@sync_job=true;`来设置同步模式，同步模式下，命令执行完毕后才会返回，否则会立即返回离线Job的Job info，需要通过`SHOW JOB `来查询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#离线命令配置详情)。 diff --git a/docs/zh/quickstart/openmldb_quickstart.md b/docs/zh/quickstart/openmldb_quickstart.md index 373c057f7a0..286c38e0b15 100644 --- a/docs/zh/quickstart/openmldb_quickstart.md +++ b/docs/zh/quickstart/openmldb_quickstart.md @@ -91,7 +91,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 `查看stdout中的查询打印结果。 + +最可靠的方式是，可以使用 `SELECT INTO` 命令，将数据导出到指定目录，或直接查看导入后的存储地址。 ```{note} OpenMLDB 也支持链接形式的软拷贝来导入离线数据，无需数据硬拷贝。可以参考 [LOAD DATA INFILE 文档](../openmldb_sql/dml/LOAD_DATA_STATEMENT.md) 的参数 `deep_copy` 的说明。 diff --git a/docs/zh/quickstart/sdk/java_sdk.md b/docs/zh/quickstart/sdk/java_sdk.md index 446330c2782..757cc043dd0 100644 --- a/docs/zh/quickstart/sdk/java_sdk.md +++ b/docs/zh/quickstart/sdk/java_sdk.md @@ -77,13 +77,9 @@ res = stmt.executeQuery("SELECT * from t1"); // 在线 select, executeQuery 可 其中，`LOAD DATA` 命令是异步命令，返回的 ResultSet 包含该 job 的 id、state 等信息。可通过执行 `show job ` 来查询 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。