数据目录、卷与共享
使用 catalog 命令组浏览和管理工作区的数据目录、数据库、表、卷(Volume)、工作区文件、数据资产与 NL2SQL 查询,并使用 data-share 命令组管理跨工作区的数据发布与数据订阅。开始前请完成 配置与身份认证。
浏览资源树与管理目录、数据库和表
写入前先调用 catalog tree 或 catalog list 获取当前工作区的目录与数据库数字 ID:
moi-cli -auth pat -o catalog tree --include-table-leaves
moi-cli -auth pat -o catalog list
moi-cli -auth pat -o catalog list-databases --catalog-id "$CATALOG_ID"
moi-cli -auth pat -o catalog preview-table --table-id "$TABLE_ID"
目录、数据库与表的常用子命令:
层级 |
子命令与核心参数 |
作用说明 |
资源树 |
catalog tree [--search <kw>] [--include-table-leaves] / catalog system-tree
|
浏览当前工作区数据资源树或系统级资源层级。 |
目录 |
catalog list / catalog create --name <name> / catalog info --catalog-id <id> / catalog update --catalog-id <id> --name <name> / catalog delete --catalog-id <id>
|
列出、创建、查看、重命名或删除数据目录。 |
数据库 |
catalog list-databases --catalog-id <id> / catalog create-database --catalog-id <id> --name <name> / catalog database-info --database-id <id> / catalog delete-database --database-id <id>
|
在指定目录下管理数据库。 |
表 |
catalog create-table --database-id <id> --name <name> --json-file <schema.json> / catalog table-info --table-id <id> / catalog preview-table --table-id <id>
|
创建表、读取表结构或预览表内样本行。 |
表导出与清理 |
catalog download-table --table-id <id> --output <path> / catalog truncate-table --table-id <id> / catalog delete-table --table-id <id>
|
导出表数据到本地文件、清空表数据或删除表。 |
需要确认建表 JSON 字段结构时,运行离线命令 moi-cli schema catalog create-table 查看线级定义。
警告
catalog truncate-table、delete-table、delete-database 与 catalog delete 会立即清空或删除目标数据对象。执行破坏性操作前,先调用 catalog table-full-path --table-id <id> 或 catalog database-info --database-id <id> 核对完整路径、数字 ID 及所属工作区。
管理卷(Volume)与文件上传下载
将本地文件写入指定数据库下的卷分为两步:先通过 catalog upload 上传文件内容拿到 file_id,再通过 catalog create-file 将该文件挂载到目标卷:
# 1) 在指定数据库下创建卷(已有目标卷时可跳过)
moi-cli -auth pat -o catalog create-volume \
--database-id "$DATABASE_ID" \
--name "raw_reports"
# 2) 上传本地文件并提取返回的 file_id
FILE_ID="$(
moi-cli -auth pat -o catalog upload --file-path ./sales_2026.csv \
| jq -er '.file_id // .id'
)"
# 3) 将上传后的文件引用注册到目标卷并核对列表
moi-cli -auth pat -o catalog create-file \
--volume-id "$VOLUME_ID" \
--file-ids "$FILE_ID"
moi-cli -auth pat -o catalog files --volume-id "$VOLUME_ID"
# 4) 从卷下载文件到本地路径
moi-cli -auth pat catalog download-file \
--volume-id "$VOLUME_ID" \
--file-id "$FILE_ID" \
--output ./downloaded_sales_2026.csv
卷、文件夹与文件的常用子命令:
子命令与核心参数 |
作用说明 |
catalog create-volume --database-id <id> --name <name> / volume-info --volume-id <id> / volume-full-path --volume-id <id> / delete-volume --volume-id <id>
|
创建、查看完整路径或删除卷。 |
catalog create-folder --parent-volume-id <vol-id> --database-id <db-id> --name <name> / delete-folder --folder-id <id> / clean-folder --folder-id <id>
|
在卷内创建、清空或删除文件夹。 |
catalog upload --file-path <path> [--filename <name>] / catalog upload-private --file-path <path>
|
上传普通工作区文件或私有文件并返回文件标识。 |
catalog create-file --volume-id <vol-id> --file-ids <id1,id2>
|
将已上传的文件 ID 关联到指定卷。 |
catalog files --volume-id <vol-id> [--name <kw>] [--extensions <ext>] / file-info --file-id <id>
|
按卷分页列出文件或查询单个文件元数据。 |
catalog download-file --volume-id <vol-id> --file-id <id> [--as-zip] --output <path>
|
下载卷内文件到本地指定路径。 |
catalog delete-file --volume-id <vol-id> --file-id <id> / delete-file-ref --volume-id <vol-id> --file-ids <ids>
|
删除卷内文件或移除文件引用。 |
查询数据资产与运行 NL2SQL
子命令与核心参数 |
作用说明 |
catalog data-asset --asset-id <id> / catalog batch-get-data-assets --raw-file-ids <ids>
|
按资产 ID 或原始文件 ID 批量查询数据资产详情。 |
catalog file-data-asset --file-id <id> / catalog file-artifact --file-id <id> / catalog batch-resolve-file-artifacts --file-ids <ids>
|
根据文件 ID 解析关联的数据资产与衍生处理产物。 |
catalog run-nl2sql --database-id <id> --sql <query-text>
|
针对指定数据库发起自然语言转 SQL 请求。 |
跨工作区数据发布与订阅(data-share)
data-share 在发布方工作区与订阅方工作区之间建立只读共享访问关系,不会复制或删除源表底层数据。
发布方:检查源表与工作区并创建发布
# 1) 查看源数据库下可发布的源表及目标工作区名称映射
moi-cli -auth pat -o data-share source-tables --source-database-id "$SOURCE_DB_ID"
moi-cli -auth pat -o data-share check-publish-name --name "finance_orders_share"
moi-cli -auth pat -o data-share resolve-workspace-names --ids "$TARGET_WORKSPACE_ID"
# 2) 创建数据发布并回读发布列表
moi-cli -auth pat -o data-share create-publish \
--name "finance_orders_share" \
--source-database-id "$SOURCE_DB_ID" \
--selected \
--table-ids "$TABLE_ID_1,$TABLE_ID_2" \
--target-workspace-ids "$TARGET_WORKSPACE_ID" \
--remark "Shared order tables for BI workspace"
moi-cli -auth pat -o data-share publishes
moi-cli -auth pat -o data-share publish-summary
订阅方:查看可订阅列表并建立订阅
切换到目标订阅工作区后,查询可见订阅并绑定本地订阅库名:
moi-cli -auth pat -workspace-id "$TARGET_WORKSPACE_ID" -o data-share subscriptions
moi-cli -auth pat -workspace-id "$TARGET_WORKSPACE_ID" -o data-share subscribe \
--subscription-id "$SUBSCRIPTION_ID" \
--sub-name "shared_finance_orders"
数据共享完整子命令速查:
子命令与核心参数 |
作用说明 |
data-share source-tables --source-database-id <db-id>
|
列出指定源数据库下允许加入发布的表。 |
data-share check-publish-name --name <name>
|
仅检查发布名称是否可用,不创建发布。 |
data-share resolve-workspace-names --ids <ws-ids> / workspace-names-result --ids <ws-ids>
|
解析并核实目标工作区 ID 与工作区名称的对应关系。 |
data-share create-publish / update-publish --publish-id <id> / delete-publish --publish-id <id>
|
创建、调整源表或目标工作区范围,或删除已有数据发布。 |
data-share publishes / publish-summary
|
查询当前工作区的发布列表与发布汇总信息。 |
data-share subscriptions [--status <status>] / subscribe --subscription-id <id> --sub-name <name> / unsubscribe --subscription-id <id>
|
查询订阅列表、挂载订阅库或取消订阅。 |
限制和注意事项
catalog upload 与 catalog upload-private 默认单次最多读入 64 MiB 本地文件字节;上传更大文件时显式附加 --max-upload-bytes <bytes>(见 命令参考)。
私有上传命令(upload-private、upload-private-file、upload-private-bytes)写入的对象同样受工作区角色权限与卷访问边界约束。
执行 data-share delete-publish 或 data-share unsubscribe 会立即撤销下游工作区对共享表的查询可见性;操作前请先确认下游看板、SQL 任务或工作流不再依赖该订阅库。
最后更新于