OpenMLDB SQL 开发调试神器 - OpenMLDB SQL Emulator

今天为大家介绍一款来自 OpenMLDB 社区的优秀独立工具 - OpenMLDB SQL Simulator（https://github.com/vagetablechicken/OpenMLDBSQLEmulator），可以让你更加高效方便的开发、调试 OpenMLDB SQL。

为了高效的实现时序特征计算，OpenMLDB SQL 对标准 SQL 做了改进和扩展，因此初学者在使用 OpenMLDB SQL 的时候，经常会碰到语法不熟悉、执行模式混淆等问题。如果直接在 OpenMLDB 上进行开发、调试，由于部署、构建索引、大数据量等问题，经常会浪费大量时间在无关任务上，并且可能无法找到 SQL 本身的错误原因。OpenMLDB SQL Emulator 是一个轻量级 OpenMLDB SQL 模拟开发调试工具，可以在脱离 OpenMLDB 集群部署的情况下，进行 SQL 的验证和调试操作，堪称 OpenMLDB SQL 的开发调试神器。我们强烈推荐此工具给我们的应用开发人员，可以首先基于此工具快速验证 SQL 的正确性、可上线性以后，再切换到 OpenMLDB 真实环境上进行部署上线。

安装和启动

从项目页面下载运行包 emulator-1.0.jar https://github.com/vagetablechicken/OpenMLDBSQLEmulator/releases，使用如下方式启动（注意当前发布的 1.0 版本对应于 OpenMLDB 0.8.3 的 SQL 语法）：

java -jar emulator-1.0.jar

注意，如果想使用 run 命令执行 SQL 来验证结果，还需要同时下载该页面下的 toydb_run_engine，并且存放在系统 /tmp 目录下。

创建虚拟数据库和表

启动后，将直接进入到默认的数据库 emudb，不需要额外创建数据库。

数据库不需要被显式创建，只需要use <db name>或建表时指定数据库名，即可自动创建数据库。
使用命令 addtable 或者 t 来创建虚拟表，重复创建同名表就是更新操作，将使用最新的表schema。我们使用简化的类 SQL 语法管理表，比如下面的例子创建了一个含有两列的表。

addtable t1 a int, b int64

使用命令 showtables 或者 st 来查看当前所有的数据库和表。

验证 OpenMLDB SQL

OpenMLDB SQL 是否可以上线，在集群中可以使用 DEPLOY 进行上线测试，但是需要管理 DEPLOYMENT 与索引。例如，如果不需要某些测试用的 DEPLOYMENT，需要手动删除；如果创建了不需要的索引，还需要清理索引。所以，我们建议在 Emulator 中测试验证，你可以使用val和valreq分别进行在线批模式和在线请求模式（即服务部署上线）的 OpenMLDB SQL 验证。例如，我们测试一个 SQL 是否能被 DEPLOY 上线，使用 valreq 命令：

addtable t1 a int, b int64
valreq select count(*) over w1 from t1 window w1 as (partition by a order by b rows between unbounded preceding and current row);

如果测试不通过，将打印 SQL 编译错误；通过则打印“validate * success”。整个过程在虚拟环境中，无需担心建表后的资源占用，也没有任何副作用。只要 valreq 验证通过的 SQL，则一定能在真实集群中上线。

测试运行 OpenMLDB SQL

OpenMLDB Emulator 也可以返回计算结果，用于测试 SQL 计算是否符合预期。你可以在其中不断进行计算和上线验证，直到调试得到最终的上线SQL。该功能可以通过 Emulator 的 run 命令实现。注意，使用run命令需要额外的 toydb_run_engine 支持，可以使用自带 toydb 的 emulator 包，或在此页面下载 https://github.com/vagetablechicken/OpenMLDBSQLEmulator/releases） toydb 程序，并将其直接放入/tmp中。
假设 Emulator 已有 toydb，测试运行步骤如下：

# step 1, generate a yaml template
gencase
# step 2, modify the yaml file to add table and data
# ...
# step 3, load yaml to get table catalog, 
# then using val/valreq sql to validate the sql in emulator
loadcase
valreq <sql>
# step 4, dump the sql, this will rewrite the yaml file
dumpcase <sql># step 5, run sql using toydb
run

运行命令gencase将会生成一个yaml模版文件，默认创建目录为是/tmp/emu-case.yaml。然后，你需要编辑这个 yaml 文件，如下所示。编辑需要注意以下几点：

你必须修改表名，表 schema 及其数据，这些不可在 Emulator 中修改。
你可以修改运行 mode，接受 batch 或 request 模式。
你可以不填写 SQL，可以在 Emulator 中通过dumpcase 写入文件。常见使用方法是，先validate SQL，SQL通过校验后dump到case中，再使用 run 命令确认 SQL 的计算符合预期。
表的 indexs 也无需手动填写，dumpcase时可以根据表 schema 自动生成（indexs 并非特殊的索引，与 SQL 也无关，仅仅是创建表时需要创建至少一个索引）。如果你不使用dumpcase，那么请手动填写至少一个索引，索引没有特别要求。

# call toydb_run_engine to run this yaml file
# you can generate yaml cases for reproduction by emulator dump or by yourself# you can set the global default db
db: emudb
cases:- id: 0desc: describe this case# you can set batch modemode: requestdb: emudb # you can set default db for case, if not set, use the global default dbinputs:- name: t1db: emudb # you can set db for each table, if not set, use the default db(table db > case db > global db)# must set table schema, emulator can't do thiscolumns: ["id int", "pk1 string","col1 int32", "std_ts timestamp"]# gen by emulator, just to init table, not the deployment indexindexs: []# must set the data, emulator can't do thisdata: |1, A, 1, 15901154200002, B, 1, 1590115420000# query: only support single query, to check the result by `expect`sql: |# optional, you can just check the output, or add your expect# expect:#   schema: id:int, pk1:string, col1:int, std_ts:timestamp, w1_col1_sum:int, w2_col1_sum:int, w3_col1_sum:int#   order: id#   data: |#     1, A, 1, 1590115420000, 1, 1, 1#     2, B, 1, 1590115420000, 1, 1, 1

简单起见，我们不进行修改，直接使用这个模版来演示如何修改运行 case。在 Emulator 中，我们执行loadcase，这个 case 的表信息将被加载到 Emulator 中，可以通过st/showtables确认 case 的表加载成功。

emudb> st
emudb={t1=id:int32,pk1:string,col1:int32,std_ts:timestamp}

可以看到表信息已成功加载，我们就可以使用valreq来确认我们编写的 SQL 是语法正确且可以上线的。然后，可以对这个 SQL 进行计算测试，使用命令dumpcase和run，例如：

valreq select count(*) over w1 from t1 window w1 as (partition by id order by std_ts rows between unbounded preceding and current row);
dumpcase select count(*) over w1 from t1 window w1 as (partition by id order by std_ts rows between unbounded preceding and current row);
run

dumpcase实际是将 SQL 与默认索引写入 case 文件中，run 命令运行该 case 文件。所以，如果你足够熟练，也可以直接修改这个case文件，再在 Emulator 中使用 run 运行它，或直接使用toydb_run_engine --yaml_path=...来运行。运行后将会得到计算结果用于调试检查。

OpenMLDB SQL Emulator 还有 genddl 功能，可以帮助用户根据 SQL 直接生成最佳索引的建表语句，避免冗余索引（目前仅支持单数据库）。未来将在索引处理上，提供更简单方便的操作，指导用户进行索引管理。此外，Emulator 交互使用上，建议多使用?help和 ?list-all提示，命令均为小写，但参数填写的 SQL 不限制大小写，与 CLI 一致，SQL作为一个参数也不需要额外的双引号引用。未来将会增加命令历史、导出当前环境等功能，方便用户操作与对接真实 OpenMLDB 集群。