SQL 与数据看板

使用 moi-cli sql 与 moi-cli dashboard 浏览库表元数据、执行 SQL 查询并管理工作簿、创建与运行数据看板图表,以及查看工作区任务执行概览。执行前请先完成 配置与身份认证;工作区已写入本地配置时可省略命令中的 --workspace-id。

浏览元数据与执行 SQL 查询

运行查询前,可先列出当前工作区可见的数据库、表结构与建表语句:

moi-cli -auth pat -o sql meta-databases --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o sql meta-db-tables --workspace-id "$WORKSPACE_ID" --db-name analytics
moi-cli -auth pat -o sql meta-table-columns --workspace-id "$WORKSPACE_ID" \
  --db-name analytics --table-name daily_sales

moi-cli sql 提供异步查询链路(execute-query → describe-query → query-result)以及单命令内联返回行数据的 sql run(视安装包版本提供,可通过 moi-cli sql --help 确认):

# 方式一:单命令执行并内联返回列、行、rows_affected 与 truncated
moi-cli -auth pat -o sql run \
  --workspace-id "$WORKSPACE_ID" \
  --db analytics \
  --query 'SELECT * FROM daily_sales LIMIT 20'

# 方式二:异步提交查询 -> 轮询状态取得 statement_id -> 读取结果或导出文件
SUBMIT_JSON="$(moi-cli -auth pat -o sql execute-query \
  --workspace-id "$WORKSPACE_ID" \
  --db-name analytics \
  --query 'SELECT product_id, SUM(amount) AS total FROM daily_sales GROUP BY product_id')"

export QUERY_ID="$(printf '%s' "$SUBMIT_JSON" | jq -r '.query_id')"

DESC_JSON="$(moi-cli -auth pat -o sql describe-query \
  --workspace-id "$WORKSPACE_ID" \
  --query-id "$QUERY_ID")"

export STATEMENT_ID="$(printf '%s' "$DESC_JSON" | jq -r '.statement_id // empty')"

moi-cli -auth pat -o sql query-result \
  --workspace-id "$WORKSPACE_ID" \
  --statement-id "$STATEMENT_ID" \
  --limit 100 --offset 0

sql 命令组常用子命令与关键标识对应关系如下:

场景

子命令

关键参数与说明

异步提交、轮询与取消

execute-query(别名 execute)、describe-query(别名 describe)、kill-query(别名 kill)

execute-query 返回 query_id;describe-query 与 kill-query 接收 --query-id,查询成功后从 describe-query 响应提取 statement_id。

读取结果、详情与执行画像

query-result(别名 result)、download-query-result、query-detail、query-profile

统一接收 --statement-id "$STATEMENT_ID"(不可传入 query_id);download-query-result 通过 --output result.csv 保存结果文件。

查看查询历史

query-history-overview、query-history(别名 history)

支持按时间范围、--status、--databases、--users、--min-duration 等条件检索历史语句。

浏览与删除元数据

meta-databases、meta-db-tree、meta-db-tables(别名 meta-tables)、meta-table-info、meta-table-columns、meta-table-column-stats、meta-table-ddl、drop-meta-database、drop-meta-table、drop-meta-view

查看库表列统计与 DDL;drop-meta-* 会直接删除目标库、表或视图,执行前请核对 --db-name、--table-name 与下游依赖。

WebSocket 地址与连接探测

query-web-socket-url、connect-query-web-socket

query-web-socket-url 仅返回连接地址而不建立连接;connect-query-web-socket 验证连接握手而不提供交互式 SQL 终端。

警告

sql execute-query 进程退出码为 0 仅代表查询请求已成功提交。SQL 语法错误、权限拒绝或执行期异常记录在查询状态中,必须检查 describe-query 返回的 status 与错误信息后再读取 query-result。此外,每次 CLI 命令调用均使用独立数据库连接,不支持跨多次 CLI 命令维护 BEGIN / COMMIT 事务。

管理 SQL 工作簿与版本

使用 sql 的工作簿子命令维护保存的 SQL 脚本草稿与历史版本:

# 分页检索工作簿并查看详情与版本列表
moi-cli -auth pat -o sql workbooks --workspace-id "$WORKSPACE_ID" --search "销售" --page-size 20
moi-cli -auth pat -o sql workbook-detail --workspace-id "$WORKSPACE_ID" --workbook-id "$WORKBOOK_ID"
moi-cli -auth pat -o sql workbook-versions --workspace-id "$WORKSPACE_ID" --workbook-id "$WORKBOOK_ID"

操作

子命令

说明

创建、重命名与删除工作簿

create-workbook --name <name>、update-workbook --workbook-id <id> --name <name>、delete-workbook --workbook-id <id>

创建新工作簿、更新工作簿名称或删除不再使用的工作簿。

创建、更新与保存工作簿版本

create-workbook-version、update-workbook-version、save-workbook-version

按子命令 --help 传入 --workbook-id、--version-id 及脚本内容,避免将多行复杂 SQL 直接裸拼在未转义的 shell 参数中。

创建数据看板与查询图表

创建数据看板前,先从 Catalog 检索可用数据表的正整数 table_id(更多目录与表查询见 数据目录、卷与共享),并通过 moi-cli schema 查看请求体结构:

moi-cli -auth pat -o catalog search-data-dashboard-tables \
  --workspace-id "$WORKSPACE_ID" \
  --search "daily_sales"

moi-cli schema dashboard create
moi-cli -auth pat -o dashboard list --workspace-id "$WORKSPACE_ID" --json '{}'

将看板名称与来源表 ID 保存为 dashboard.json(跨库看板需确保当前身份对每个来源表均具备访问权限):

{
  "name": "销售分析",
  "sources": [
    {
      "table_id": 123
    },
    {
      "table_id": 456
    }
  ]
}

创建看板并保存返回的 DASHBOARD_ID:

DASHBOARD_JSON="$(moi-cli -auth pat -o dashboard create \
  --workspace-id "$WORKSPACE_ID" \
  --json-file dashboard.json)"

export DASHBOARD_ID="$(printf '%s' "$DASHBOARD_JSON" | jq -r '.id')"

生成和预览图表 SQL

使用 generate-sql 根据自然语言问题生成 SQL 草稿,核对限定表名与过滤口径后再通过 preview-sql 试运行验证:

# 生成 SQL 草稿(仅返回草稿文本,不会自动执行查询)
DRAFT_JSON="$(moi-cli -auth pat -o dashboard generate-sql \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --question '按产品统计本月销售额')"

export SQL_TEXT="$(printf '%s' "$DRAFT_JSON" | jq -r '.sql_text')"

# 预览 SQL 执行结果
moi-cli -auth pat -o dashboard preview-sql \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --sql-text "$SQL_TEXT"

创建图表、刷新运行与读取结果

图表配置中的 chart_config 与 layout_config 为编码后的 JSON 字符串,可通过 moi-cli schema 查看各图表类型的序列化字段:

moi-cli schema dashboard create-chart
moi-cli schema dashboard create-chart --argument json.chart_config
moi-cli schema dashboard create-chart --argument json.layout_config

准备 chart.json:

{
  "name": "销售明细",
  "chart_type": "table",
  "sql_text": "SELECT * FROM analytics.daily_sales LIMIT 10",
  "chart_config": "{}",
  "layout_config": "{}",
  "refresh_interval": "manual",
  "alert_enabled": false
}

创建图表、触发查询并读取或下载结果:

CHART_JSON="$(moi-cli -auth pat -o dashboard create-chart \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --json-file chart.json)"

export CHART_ID="$(printf '%s' "$CHART_JSON" | jq -r '.id')"

# 运行单个图表(刷新整张看板全部图表可使用 dashboard refresh)
moi-cli -auth pat -o dashboard run-chart \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID"

# 读取最新图表结果或导出文件
moi-cli -auth pat -o dashboard chart-result \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID"

moi-cli -auth pat -o dashboard download-chart-result \
  --workspace-id "$WORKSPACE_ID" \
  --dashboard-id "$DASHBOARD_ID" \
  --chart-id "$CHART_ID" \
  --output chart-result.csv

看板与图表维护还支持 get、update、delete、update-chart、update-chart-order、delete-chart、drill-through 和 download-drill-through(通过 moi-cli dashboard <subcommand> --help 查看选项)。

警告

dashboard update 会整体替换看板元数据:请求体中省略 description 会清空原有看板描述;移除仍被图表引用的来源表会报错 DATA_DASHBOARD_SOURCE_IN_USE。调用 update-chart-order 时须传入看板下全部图表的完整 chart_ids 排列。

查看工作区任务执行概览

使用 dashboard task-execution-overview 读取当前工作区近期后台任务的汇总计数:

moi-cli -auth pat -o dashboard task-execution-overview --workspace-id "$WORKSPACE_ID"

输出包含统计时间窗口及运行中、成功、失败、待执行和总计任务数量(JSON 输出中零值计数字段可能省略)。该命令仅返回工作区级汇总指标;需排查具体失败任务时,请分别通过 workflow、connector 或 agent 命令组列出对应任务并读取执行详情。

限制和注意事项

  • 写入、更新、删除语句及 drop-meta-* 命令会直接作用于目标工作区的数据表与元数据,执行前请确认目标数据库与角色权限。

  • dashboard run-chart 与 dashboard refresh 返回受理结果后,图表查询仍在后台执行;若 chart-result 尚未就绪,使用原 DASHBOARD_ID 和 CHART_ID 有限次重查,无需重复创建图表。

  • 读取历史时间点的图表快照时,可在 dashboard chart-result 中附加 --query-param 'at=<RFC3339Nano时间戳>'。

最后更新于