数据目录、卷与共享

使用 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 任务或工作流不再依赖该订阅库。

最后更新于