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 命令组常用子命令与关键标识对应关系如下:
场景 |
子命令 |
关键参数与说明 |
|---|---|---|
异步提交、轮询与取消 |
|
|
读取结果、详情与执行画像 |
|
统一接收 |
查看查询历史 |
|
支持按时间范围、 |
浏览与删除元数据 |
|
查看库表列统计与 DDL; |
WebSocket 地址与连接探测 |
|
|
警告
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"
操作 |
子命令 |
说明 |
|---|---|---|
创建、重命名与删除工作簿 |
|
创建新工作簿、更新工作簿名称或删除不再使用的工作簿。 |
创建、更新与保存工作簿版本 |
|
按子命令 |
创建数据看板与查询图表¶
创建数据看板前,先从 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时间戳>'。