# 数据目录、卷与共享

使用 `catalog` 命令组浏览和管理工作区的数据目录、数据库、表、卷（Volume）、工作区文件、数据资产与 NL2SQL 查询，并使用 `data-share` 命令组管理跨工作区的数据发布与数据订阅。开始前请完成 [配置与身份认证](../configuration-authentication.md)。

## 浏览资源树与管理目录、数据库和表

写入前先调用 `catalog tree` 或 `catalog list` 获取当前工作区的目录与数据库数字 ID：

```bash
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` 查看线级定义。

:::{warning}
`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` 将该文件挂载到目标卷：

```bash
# 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` 在发布方工作区与订阅方工作区之间建立只读共享访问关系，不会复制或删除源表底层数据。

### 发布方：检查源表与工作区并创建发布

```bash
# 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
```

### 订阅方：查看可订阅列表并建立订阅

切换到目标订阅工作区后，查询可见订阅并绑定本地订阅库名：

```bash
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>`（见 [命令参考](../command-reference.md)）。
- 私有上传命令（`upload-private`、`upload-private-file`、`upload-private-bytes`）写入的对象同样受工作区角色权限与卷访问边界约束。
- 执行 `data-share delete-publish` 或 `data-share unsubscribe` 会立即撤销下游工作区对共享表的查询可见性；操作前请先确认下游看板、SQL 任务或工作流不再依赖该订阅库。
