OpenMLDB 新手宝典 开发者上手必读
OpenMLDB作为分布式系统，模式多样、客户端丰富，初次使用可能会遇到安装部署或者运行使用方面的问题。
本文将从新手使用的角度，为大家讲解如何进行诊断调试，以及如何向OpenMLDB社区技术人员反馈疑问或提供清晰的使用信息。
创建 OpenMLDB 与连接
首先，我们建议不熟悉分布式多进程管理的新手使用 docker 创建 OpenMLDB，方便快速上手。待熟悉 OpenMLDB 各组件后，再尝试分布式部署。
docker 创建 OpenMLDB 可见快速上手文档（见文末），请注意文档中有两个版本，单机版和集群版。请记住自己创建的版本，不要混合使用，以致错乱。
启动成功的标准是可以使用 CLI 连接上 OpenMLDB 服务端（即使用/work/openmldb/bin/openmldb 连接 OpenMLDB，单机或集群均可以通过 CLI 连接），并且执行 show components;可以看到 OpenMLD B服务端组件的运行情况。
如果 CLI 无法连接 OpenMLDB，请先确认进程是否运行正常，可以通过 ps f|grep bin/openmldb 确认 nameserver和tabletserver 进程，集群版还需要通过 ps f | grep zoo.cfg 来确认 zk 服务，ps f | grep TaskManagerServer 来确认 taskmanager 进程。
如果所有服务进程都运行中，但 CLI 连接服务端失败，请确认 CLI 运行的参数。如果仍有问题，请联系我们并提供 CLI 的错误信息。
Note
如果我们还需要 OpenMLDB 服务端的配置和日志，可以使用诊断工具获取，见下文。
执行 SQL
OpenMLDB 所有命令均为 SQL，如果 SQL 执行失败或交互有问题（不知道命令是否执行成功），请先确认 SQL 书写是否有误，命令并未执行，还是命令进入了执行阶段。
例如，下面提示 Syntax error 的是SQL书写有误，请参考 sql reference 纠正错误。
127.0.0.1:7527/db> create table t1(c1 int;
Error: Syntax error: Expected ")" or "," but got ";" [at 1:23]
create table t1(c1 int; ^
如果是命令进入执行阶段，但执行失败或交互失败，需要明确以下几点：
- OpenMLDB 是单机还是集群？
- 执行模式是什么？CLI 运行命令时可以使用
show variable获取，但注意单机版的执行模式没有意义。
我们需要特别注意集群版的一些使用逻辑。
集群
离线
如果是集群离线命令，默认异步模式下，发送命令会得到 job id 的返回。可使用show job <id>来查询 job 执行情况。
离线 job 如果是 SELECT（并不 INTO 保存结果），也不会将结果打印在客户端。需要从日志中获得结果，日志默认在/work/openmldb/taskmanager/bin/logs/jog_x.log。
如果发现 job failed 或者 finished，但不符合你的预期，请查询日志。日志默认在/work/openmldb/taskmanager/bin/logs/jog_x_error.log (注意有 error 后缀)，
日志地址由 taskmanager.properties 的 job.log.path 配置，如果你改变了此配置项，需要到配置的目的地寻找日志。
Note
- 如果 taskmanager 是 yarn 模式，而不是 local 模式，
job_x_error.log中的信息会较少，不会有 job 错误的详细信息。需要通过job_x_error.log中记录的 yarn app id，去 yarn 系统中查询 job 的真正错误原因。
在线
集群版在线模式下，我们通常只推荐使用 DEPLOY 创建 deployment 和执行 deployment 做实时特征计算。在 CLI 或其他客户端中，直接在在线中进行 SELECT查询，称为“在线预览”。在线预览有诸多限制，详情请参考功能边界-集群版在线预览模式，请不要执行不支持的 SQL。
提供复现脚本
如果你通过自主诊断，无法解决问题，请向我们提供复现脚本。一个完整的复现脚本，如下所示：
create database db;
use db;
-- create youer table
create table xx ();
-- offline or online
set @@execute_mode='';
-- load data or online insert
-- load data infile '' into table xx;
-- insert into xx values (),();
-- query / deploy ...
如果你的问题需要数据才能复现，请提供数据。如果是离线数据，离线无法支持 insert，请提供 csv/parquet 数据文件。如果是在线数据，可以提供数据文件，也可以直接在脚本中进行 insert。
这样的数据脚本可以通过重定向符号，批量执行 sql 脚本中的命令。
/work/openmldb/bin/openmldb --host 127.0.0.1 --port 6527 < reproduce.sql
/work/openmldb/bin/openmldb --zk_cluster=127.0.0.1:2181 --zk_root_path=/openmldb --role=sql_client < reproduce.sql
请确保在你本地可以使用复现脚本复现问题，再记录 issue 或发送给我们。
！Caution
请注意离线 job 默认为异步。如果你需要离线导入再查询，请设置为同步模式，详情见配置离线命令同步执行。否则导入还未完成就进行查询，是无意义的。
提供配置与日志
如果你的问题无法通过复现脚本复现，那么，就需要你提供客户端和服务端的配置与日志，以便我们调查。
docker 或本地的集群（服务端所有进程都在本地），可以使用诊断工具快速获取配置、日志等信息。
使用 init.sh/start-all.sh 脚本启动的 OpenMLDB 服务端，可以使用以下命令进行诊断，分别对应集群版和单机版。
openmldb_tool --env=onebox --dist_conf=cluster_dist.yml
openmldb_tool --env=onebox --dist_conf=stadnalone_dist.yml
cluster_dist.yml 和 stadnalone_dist.yml，可在 docker 容器/work/diag 目录中找到，或将github目录中的yml文件复制下来使用。
如果是分布式的集群，需要配置 ssh 免密才能顺利使用诊断工具，参考文档诊断工具。
如果你的环境无法做到，请手动获取配置与日志。
本期 · 相关资料
OpenMLDB 快速上手文档
网址：http://openmldb.ai/docs/zh/main/quickstart/openmldb_quickstart.html
了解更多
Github 网址：https://github.com/4paradigm/OpenMLDB
微信交流群网址：http://qr61.cn/o9EEV6/qcGz53S
