OpenMLDB SQL 開發除錯神器 - OpenMLDB SQL Emulator

今天為大家介紹一款來自 OpenMLDB 社群的優秀獨立工具 - OpenMLDB SQL Simulator（ ） ，可以讓你更加高效方便的開發、除錯 OpenMLDB SQL。

為了高效的實現時序特徵計算，OpenMLDB SQL 對標準 SQL 做了改進和擴充套件，因此初學者在使用 OpenMLDB SQL 的時候，經常會碰到語法不熟悉、執行模式混淆等問題。如果直接在 OpenMLDB 上進行開發、除錯，由於部署、構建索引、大資料量等問題，經常會浪費大量時間在無關任務上，並且可能無法找到 SQL 本身的錯誤原因。OpenMLDB SQL Emulator 是一個輕量級 OpenMLDB SQL 模擬開發除錯工具，可以在脫離 OpenMLDB 叢集部署的情況下，進行 SQL 的驗證和除錯操作，堪稱 OpenMLDB SQL 的開發除錯神器。我們強烈推薦此工具給我們的應用開發人員，可以首先基於此工具快速驗證 SQL 的正確性、可上線性以後，再切換到 OpenMLDB 真實環境上進行部署上線。

安裝和啟動

從專案頁面下載執行包 `emulator-1.0.jar`  /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 包，或在此頁面下載  /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` <sql>寫入檔案。常見使用方法是，先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 進行計算測試，使用命令`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 叢集。

相關閱讀

- OpenMLDB 官網：  OpenMLDB - 生產級特徵開發全棧解決方案

- OpenMLDB GitHub 主頁：  https:// github.com/4paradigm/Op enMLDB

- OpenMLDB 文件：  https:// openmldb.ai/docs/zh/

- OpenMLDB 微信交流群