今天为大家介绍一款来自 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 中测试验证,你可以使用valvalreq分别进行在线批模式和在线请求模式(即服务部署上线)的 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: 0
    desc: describe this case
    # you can set batch mode
    mode: request
    db: emudb # you can set default db for case, if not set, use the global default db
    inputs:
      - name: t1
        db: 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 this
        columns: ["id int", "pk1 string","col1 int32", "std_ts timestamp"]
        # gen by emulator, just to init table, not the deployment index
        indexs: []
        # must set the data, emulator can't do this
        data: |
          1, A, 1, 1590115420000
          2, 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 进行计算测试,使用命令dumpcaserun,例如:

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 集群。

相关阅读

  • OpenMLDB 官网: https://openmldb.ai/
  • OpenMLDB GitHub 主页: https://github.com/4paradigm/OpenMLDB
  • OpenMLDB 文档: https://openmldb.ai/docs/zh/
  • OpenMLDB 微信交流群

Logo

开放原子开发者工作坊旨在鼓励更多人参与开源活动,与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动,如meetup、训练营等,主打技术交流,干货满满,真诚地邀请各位开发者共同参与!

更多推荐