docs: fix boundary, add more about maintain (#3519)

* docs: fix boundary about deploy and diag rpc desc

* doc about beginner, boundary

* storage

* apiserver refresh desc

---------

Co-authored-by: Huang Wei <huangwei@4paradigm.com>

Author: vagetablechicken

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，如果你不确定，可以两者都调节。

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;
-```
+```

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 支持

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日志通常在`<dir>/taskmanager/bin/logs`中，其他组件日志均在`<dir>/logs`中。如有特别配置，以配置项为准。
+
+- 手动部署
+手动部署只要使用脚本`bin/start.sh`和`conf/`目录中的配置文件（非template结尾）。唯一需要注意的是，`spark.home`可以为空，那么会读取`SPARK_HOME`环境变量。如果你认为环境变量有问题，导致启动不了TaskManager，推荐写配置`spark.home`。
+
+手动部署的组件日志文件，以运行`bin/start.sh`的目录为准，TaskManager日志通常在`<dir>/taskmanager/bin/logs`中，其他组件日志均在`<dir>/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)。
 
 ## 源数据
 

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 <deploy_name> <sql>` 可以部署上线 SQL 方案，这个操作也会自动解析 SQL 帮助创建索引（可以通过 `DESC <table_name>` 查看索引详情），详情可参考 [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 边界
 

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

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