diff --git a/docs/zh/faq/client_faq.md b/docs/zh/faq/client_faq.md
index 894cca02e57..3b3bff7e93c 100644
--- a/docs/zh/faq/client_faq.md
+++ b/docs/zh/faq/client_faq.md
@@ -76,13 +76,21 @@ sdk日志(glog日志):
## 离线命令Spark报错
-`java.lang.OutOfMemoryError: Java heap space`
-
-离线命令的Spark配置默认为`local[*]`,并发较高可能出现OutOfMemoryError错误,请调整`spark.driver.memory`和`spark.executor.memory`两个spark配置项。可以写在TaskManager运行目录的`conf/taskmanager.properties`的`spark.default.conf`并重启TaskManager,或者使用CLI客户端进行配置,参考[客户端Spark配置文件](../reference/client_config/client_spark_config.md)。
```
-spark.default.conf=spark.driver.memory=16g;spark.executor.memory=16g
+java.lang.OutOfMemoryError: Java heap space
```
+```
Container killed by YARN for exceeding memory limits. 5 GB of 5 GB physical memory used. Consider boosting spark.yarn.executor.memoryOverhead.
+```
+
+出现以上几种日志时,说明离线任务所需资源多于当前配置。一般是这几种情况:
+- 离线命令的Spark配置`local[*]`,机器核数较多,并发度很高,资源占用过大
+- memory配置较小
+
+如果是local模式,单机资源比较有限,可以考虑降低并发度。如果不降低并发,请调整`spark.driver.memory`和`spark.executor.memory`两个spark配置项。可以写在TaskManager运行目录的`conf/taskmanager.properties`的`spark.default.conf`并重启TaskManager,或者使用CLI客户端进行配置,参考[客户端Spark配置文件](../reference/client_config/client_spark_config.md)。
+```
+spark.default.conf=spark.driver.memory=16g;spark.executor.memory=16g
+```
-local时drivermemory
+master为local时,不是调整executor的,而是driver的memory,如果你不确定,可以两者都调节。
diff --git a/docs/zh/openmldb_sql/dml/DELETE_STATEMENT.md b/docs/zh/openmldb_sql/dml/DELETE_STATEMENT.md
index bab4225252d..716af9351fd 100644
--- a/docs/zh/openmldb_sql/dml/DELETE_STATEMENT.md
+++ b/docs/zh/openmldb_sql/dml/DELETE_STATEMENT.md
@@ -12,7 +12,7 @@ TableName ::=
**说明**
-- `DELETE` 语句删除在线表满足指定条件的数据
+- `DELETE` 语句删除在线表满足指定条件的数据,删除并不是所有索引中满足条件的数据都被删除,只会删除与where condition相关的索引,示例见[功能边界](../../quickstart/function_boundary.md#delete)。
- `WHERE` 指定的筛选列必须是索引列。如果是key列只能用等于
## Examples
@@ -25,4 +25,4 @@ DELETE FROM t1 WHERE col1 = 'aaaa' and ts_col = 1687145994000;
DELETE FROM t1 WHERE col1 = 'aaaa' and ts_col > 1687059594000 and ts_col < 1687145994000;
DELETE FROM t1 WHERE ts_col > 1687059594000 and ts_col < 1687145994000;
-```
\ No newline at end of file
+```
diff --git a/docs/zh/openmldb_sql/dml/LOAD_DATA_STATEMENT.md b/docs/zh/openmldb_sql/dml/LOAD_DATA_STATEMENT.md
index 6be6d934f5f..b51ab8306d3 100644
--- a/docs/zh/openmldb_sql/dml/LOAD_DATA_STATEMENT.md
+++ b/docs/zh/openmldb_sql/dml/LOAD_DATA_STATEMENT.md
@@ -1,6 +1,10 @@
# LOAD DATA INFILE
`LOAD DATA INFILE`语句能高效地将文件中的数据读取到数据库中的表中。`LOAD DATA INFILE` 与 `SELECT INTO OUTFILE`互补。要将数据从 table导出到文件,请使用[SELECT INTO OUTFILE](../dql/SELECT_INTO_STATEMENT.md)。要将文件数据导入到 table 中,请使用`LOAD DATA INFILE`。
+```{note}
+INFILE 的 filePath,既可以是单个文件名,也可以是目录,也可以使用`*`通配符。如果目录中存在多格式的文件,只会选择 LoadDataInfileOptionsList 中指定的FORMAT格式文件。具体格式等价于`DataFrameReader.read.load(String)`,可以使用spark shell来read你想要的文件路径,确认能否读入成功。
+```
+
## Syntax
```sql
@@ -70,7 +74,7 @@ FilePathPattern
## SQL语句模版
```sql
-LOAD DATA INFILE 'file_name' INTO TABLE 'table_name' OPTIONS (key = value, ...);
+LOAD DATA INFILE 'file_path' INTO TABLE 'table_name' OPTIONS (key = value, ...);
```
## Hive 支持
diff --git a/docs/zh/quickstart/beginner_must_read.md b/docs/zh/quickstart/beginner_must_read.md
index 117ad6fedb7..60522283942 100644
--- a/docs/zh/quickstart/beginner_must_read.md
+++ b/docs/zh/quickstart/beginner_must_read.md
@@ -32,19 +32,42 @@ docker创建OpenMLDB见[快速上手](./openmldb_quickstart.md),请注意文
如果我们还需要OpenMLDB服务端的配置和日志,可以使用诊断工具获取,见[下文](#提供配置与日志获得技术支持)。
```
-### 运维
+### 部署工具说明
-集群各组件进程启动后,在使用过程中可能遇到各种变化,比如服务进程意外退出,需要重启服务进程,或者需要扩容服务进程。
+请确定你使用的是什么部署方式,通常我们只考虑两种部署方式,见[安装部署](../deploy/install_deploy.md),“一键部署”也被称为sbin部署方式。配置文件如何修改,日志文件在何处,都与部署方式联系紧密,所以必须准确。
-如果你需要保留已有的在线表,**不要主动地kill全部Tablet再重启**,保证Tablet只有单台在上下线。`stop-all.sh`和`start-all.sh`脚本是给快速重建集群用的,可能会导致在线表数据恢复失败,**不保证能修复**。
+- sbin部署
+sbin部署会经过deploy(拷贝安装包至各个节点),再启动组件。需要明确的是,部署节点就是执行sbin的节点,尽量不要在运维中更换目录。deploy到hosts中各个节点的目录中,这些节点的目录我们称为运行目录。
-当你发现进程变化或者主动操作其变化后,需要使用诊断工具进行诊断,确认集群状态是否正常:
-```bash
-openmldb_tool inspect # 主要命令
-openmldb_tool status --diff hosts # 可检查TaskManager等是否掉线,当然,你也可以手动判断
-```
+配置文件会在deploy阶段,从template文件生成,所以,如果你要修改某组件的配置,不要在节点上修改,需要在部署地点修改template文件。如果你不进行deploy操作,可以在节点运行目录上原地修改配置文件(非template),但deploy将覆盖修改,需要谨慎处理。
+
+出现任何非预期的情况,以sbin部署的最终配置文件,即组件节点的运行目录中的配置文件为准。运行目录查看`conf/hosts`,例如,`localhost:10921 /tmp/openmldb/tablet-1`说明tablet1的运行目录是`/tmp/openmldb/tablet-1`,`localhost:7527`目录为空说明该组件就运行在`$OPENMLDB_HOME`(如未指定,就是指部署目录)。如果你无法自行解决,提供最终配置文件给我们。
+
+sbin日志文件地址,需要先查看hosts确认组件节点的运行目录,TaskManager日志通常在`
/taskmanager/bin/logs`中,其他组件日志均在`/logs`中。如有特别配置,以配置项为准。
+
+- 手动部署
+手动部署只要使用脚本`bin/start.sh`和`conf/`目录中的配置文件(非template结尾)。唯一需要注意的是,`spark.home`可以为空,那么会读取`SPARK_HOME`环境变量。如果你认为环境变量有问题,导致启动不了TaskManager,推荐写配置`spark.home`。
+
+手动部署的组件日志文件,以运行`bin/start.sh`的目录为准,TaskManager日志通常在`/taskmanager/bin/logs`中,其他组件日志均在`/logs`中。如有特别配置,以配置项为准。
+
+## 运维
+
+- 上文提到,inspect能帮我们检查集群状态,如果有问题,可使用recoverdata工具。但这是事后修复手段,通常情况下,我们应该通过正确的运维手段避免这类问题。需要上下线节点时,**不要主动地kill全部Tablet再重启**。请尽量用扩缩容的方式来操作,详情见[扩缩容](../maintain/scale.md)。
+ - 如果你认为已有数据不重要,更需要快速地上下线,那么可以直接重启节点。`stop-all.sh`和`start-all.sh`脚本是给快速重建集群用的,可能会导致在线表数据恢复失败,**不保证能修复**。
+
+- 各组件在长期服务中也可能出现网络抖动、慢节点等复杂问题,请开启[监控](../maintain/monitoring.md)。如果监控中服务端表现正常,可以怀疑是你的客户端或网络问题。如果监控中服务端就出现延迟高,qps低等情况,请向我们提供相关监控图。
+
+## 理解存储
+
+OpenMLDB是在线离线存储计算分离的,所以,你需要明确自己导入数据或查询数据是处于在线模式还是离线模式。
+
+离线存储在HDFS等地,如果你认为导入到离线存储的数据有缺漏,需要到存储地点进行进一步检查。
+
+在线存储需要注意以下几点:
+- 在线存储是有TTL概念的,所以,如果你导入数据后检查发现数据少了,可能是数据因为过期被淘汰了。
+- 在线存储适合使用`select count(*) from t1`和`show table status`来检查条数,请不要使用`select * from t1`来检查,可能有数据截断,这种查询只适合预览数据。
-如果诊断出server offline,或是TaskManager等掉线,需要先启动回来。如果启动失败,请查看对应日志,提供错误信息。如果诊断结果提示需要recoverdata,请参考[OpenMLDB运维工具](../maintain/openmldb_ops.md)执行recoverdata。如果recoverdata脚本提示recover失败,或recover成功后再次inpsect的结果仍然不正常,请提供日志给我们。
+关于如何设计你的数据流入流出,可参考[实时决策系统中 OpenMLDB 的常见架构整合方式](../tutorial/app_arch.md)。
## 源数据
diff --git a/docs/zh/quickstart/function_boundary.md b/docs/zh/quickstart/function_boundary.md
index 5d656f8eb75..30fa4285a59 100644
--- a/docs/zh/quickstart/function_boundary.md
+++ b/docs/zh/quickstart/function_boundary.md
@@ -8,7 +8,7 @@
## 系统配置——TaskManager
-通过配置 TaskManager 可以决定离线存储地址 `offline.data.prefix`、离线 job 计算所需 Spark 模式 `spark.master` 等。
+通过配置 TaskManager 可以决定离线存储地址 `offline.data.prefix`、离线 job 计算所需 Spark 模式 `spark.master` 等。
`offline.data.prefix`:可配置为文件路径或 HDFS 路径。生产环境建议配置 HDFS 路径,测试环境(特指 onebox 型,例如在 Docker 容器内启动)可以配置本地文件路径。文件路径作为离线存储,将无法支持多 TaskManager 分布式部署(TaskManager 之间不会传输数据)。如果想在多台主机上部署 TaskManager,请使用 HDFS 等多机可同时访问到的存储介质。如果想测试多 TaskManager 工作协同,可以在一台主机上部署多个 TaskManager,此时可以使用文件路径作为离线存储。
@@ -24,11 +24,15 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar
`spark.port.maxRetries`:默认为 16,参考 [Spark 配置](https://spark.apache.org/docs/3.1.2/configuration.html)。每个离线 job 都会绑定 Spark UI,对应一个 port。每次 port 都是从默认初始端口开始尝试绑定,retry 即绑定下一个端口 port+1,如果同时运行的 job 大于 `spark.port.maxRetries`,retry 次数也就大于 `spark.port.maxRetries`,job 就会启动失败。如果你需要更大的 job 并发,请配置更大的 `spark.port.maxRetries`,重启 TaskManager 生效。
+### 临时Spark配置
+
+见[客户端Spark配置文件](../reference/client_config/client_spark_config.md),CLI支持临时更改Spark配置,不需要重启TaskManager。但此配置方式不可以改变spark.master等配置。
+
## DDL 边界——DEPLOY 语句
通过 `DEPLOY ` 可以部署上线 SQL 方案,这个操作也会自动解析 SQL 帮助创建索引(可以通过 `DESC ` 查看索引详情),详情可参考 [DEPLOY STATEMENT](../openmldb_sql/deployment_manage/DEPLOY_STATEMENT.md)。
-部署操作是否成功,跟表的在线数据有一定关系。
+部署上线操作成功后,可能会创建索引,索引还会后台进行数据复制。所以,如果要保证DEPLOYMENT可以开始使用,需要查看后台复制Nameserver OP的情况,或DEPLOY时添加SYNC配置,详情见语法文档。
### 长窗口 SQL
@@ -37,17 +41,18 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar
### 普通 SQL
- 如果部署之前已存在相关的索引,那么这一次部署操作不会创建索引。无论表中有无在线数据,`DEPLOY` 操作将成功。
-- 如果部署时需要创建新的索引,而此时表中已有在线数据,那么 `DEPLOY` 操作将失败。
+ - 如果索引需要更新ttl,仅更新ttl value是可以成功的,但ttl更新生效需要2个gc interval,并且更新ttl前被淘汰的数据不会找回。如果ttl需要更新type,在<0.8.1的版本中将会失败,>=0.8.1的版本可以成功。
+- 如果部署时需要创建新的索引,而此时表中已有在线数据,版本<0.8.1将 `DEPLOY` 失败,>=0.8.1将在后台进行数据复制到新索引,需要等待一定时间。
-解决方案有两种:
+对于**旧版本**解决方案有两种:
- 严格保持先 `DEPLOY` 再导入在线数据,不要在表中有在线数据后做 `DEPLOY`。
-- `CRATE INDEX` 语句可以在创建新索引时,自动导入已存在的在线数据(已有索引里的数据)。如果一定需要在表已有在线数据的情况下 `DEPLOY`,可以先手动 `CRATE INDEX` 创建需要的索引(新索引就有数据了),再 `DEPLOY`(这时的 `DEPLOY` 不会创建新索引,计算时直接使用手动创建的那些索引)。
+- `CRATE INDEX` 语句可以在创建新索引时,自动导入已存在的在线数据(已有索引里的数据)。如果一定需要在表已有在线数据的情况下 `DEPLOY`,可以先手动 `CREATE INDEX` 创建需要的索引(新索引就有数据了),再 `DEPLOY`(这时的 `DEPLOY` 不会创建新索引,计算时直接使用手动创建的那些索引)。
```{note}
-如何知道应该创建哪些索引?
+如果你只能使用旧版本,如何知道应该创建哪些索引?
-目前只有 Java SDK 支持,可以通过 `SqlClusterExecutor.genDDL` 获取需要创建的所有索引。(但 `genDDL` 是获得建表语句,所以需要手动转换为 `CREATE INDEX`。) 未来将支持**直接获取创建索引语句**,或支持 `DEPLOY` **自动导入数据到新索引**。
+目前没有太直接的方法。推荐通过[OpenMLDB SQL Emulator](https://github.com/vagetablechicken/OpenMLDBSQLEmulator) genddl获得建表语句,其中有创建的索引配置。 Java SDK 也支持,可以通过 `SqlClusterExecutor.genDDL` 获取需要创建的所有索引(静态方法,无需连接集群),但需要额外编码。而且 `genDDL` 是获得建表语句,所以需要手动转换为 `CREATE INDEX`。
```
## DML 边界
@@ -71,11 +76,17 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar
- TaskManager 是 local 模式,只有将源数据放在 TaskManager 进程的主机上才能顺利导入。
- TaskManager 是 yarn (client and cluster) 模式时,由于不知道运行容器是哪台主机,不可使用文件路径作为源数据地址。
+#### ONLINE LOAD DATA
+
+在线导入还需要考虑并发问题,在线导入本质上是Spark中每个partition task启动一个Java SDK,每个SDK会创建一个与zk之间的session,如果并发过高,同时活跃的task过多,zk的session数量就会很大,可能超过其限制`maxClientCnxns`,具体问题现象见[issue 3219](https://github.com/4paradigm/OpenMLDB/issues/3219)。简单来说,请注意你的导入任务并发数和单个导入任务的并发数,如果你同时会进行多个导入任务,建议降低单个导入任务的并发数。
+
+单个任务最大的并发数限制为`spark.executor.instances`*`spark.executor.cores`,请调整这两个配置。当spark.master=local时,调整driver的,而不是executor的。
+
### DELETE
在线存储的表有多索引,`DELETE` 可能无法删除所有索引中的对应数据,所以,可能出现删除了数据,却能查出已删除数据的情况。
-举例说明:
+举例:
```SQL
create database db;
@@ -126,7 +137,7 @@ select * from t1 where c2=2;
说明:
-表 `t1` 有多个索引(`DEPLOY` 也可能自动创建出多索引),`delete from t1 where c2=2` 实际只删除了第二个 index 的数据,第一个 index 数据没有被影响。所以 `select * from t1` 使用第一个索引,结果会有两条数据,并没有删除,`select * from t1 where c2=2` 使用第二个索引,结果为空,数据已被删除。
+表 `t1` 有多个索引(`DEPLOY` 也可能自动创建出多索引),`delete from t1 where c2=2` 实际只删除了第二个 index 的数据,第一个 index 数据没有被影响。这是因为delete的where condition只与第二个index相关,第一个index中没有任何该condition相关的key或ts。而 `select * from t1` 使用第一个索引,并非第二个,结果就会有两条数据,直观感受为delete失败了;`select * from t1 where c2=2` 使用第二个索引,结果为空,证明数据在该索引下已被删除。
## DQL 边界
diff --git a/docs/zh/quickstart/sdk/rest_api.md b/docs/zh/quickstart/sdk/rest_api.md
index 0a225e444f6..8e088131369 100644
--- a/docs/zh/quickstart/sdk/rest_api.md
+++ b/docs/zh/quickstart/sdk/rest_api.md
@@ -320,6 +320,8 @@ curl http://127.0.0.1:8080/dbs/demo_db/deployments/demo_data_service -X POST -d'
## 刷新 APIServer 元数据缓存
+创建删除表、Deploymennt等操作后,元数据同步有一定的滞后性。如果你发现APIServer找不到新建的表或Deployment,请先尝试刷新缓存。
+
请求地址:http://ip:port/refresh
请求方式:POST
diff --git a/docs/zh/use_case/JD_recommendation.md b/docs/zh/use_case/JD_recommendation.md
index 6cf586a397f..a0a98d1c752 100644
--- a/docs/zh/use_case/JD_recommendation.md
+++ b/docs/zh/use_case/JD_recommendation.md
@@ -306,7 +306,8 @@ python preprocess.py $demodir/out/1
`$demodir/out/1` 即上一步 OpenMLDB 计算得到的特征数据目录。
-脚本将在 `$demodir/feature_preprocess/out` 对应生成 train、test、valid 三个 Parquet 数据集,并将三者的行数和 `table_size_array` 保存在文件 `data_info.txt` 中(下一步可以直接使用 info 文件,不需要手动填写参数)。运行结果打印类似:
+具体来讲,脚本将对列重命名,将 命名为Label,也就是选择此列为标签列。然后,进行切分,
+在 `$demodir/feature_preprocess/out` 对应生成 train、test、valid 三个 Parquet 数据集,并将三者的行数和 `table_size_array` 保存在文件 `data_info.txt` 中(下一步可以直接使用 info 文件,不需要手动填写参数)。运行结果打印类似:
```
feature total count: 13916