<span id="数据目录、卷与共享"></span>
<span id="目录、数据库、表、卷和文件"></span>
<span id="目录数据库表卷和文件"></span>
<span id="数据分享：数据发布与数据订阅"></span>

# Catalogs, Volumes, and Data Sharing

Use the `catalog` command group to browse and manage workspace catalogs, databases, tables, volumes, files, data assets, and NL2SQL requests, and use `data-share` to manage cross-workspace data publications and subscriptions. Complete [Configuration and Authentication](../configuration-authentication.md) before running these commands.

<span id="浏览资源树与管理目录、数据库和表"></span>
<span id="常用操作"></span>

## Browse the resource tree and manage catalogs, databases, and tables

Inspect the workspace resource tree and list catalogs first to obtain numeric catalog, database, and table IDs before mutating resources:

```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"
```

Common catalog, database, and table subcommands:

| Level | Subcommands and key flags | Description |
| --- | --- | --- |
| Resource tree | `catalog tree [--search <kw>] [--include-table-leaves]` / `catalog system-tree` | Browse the workspace resource hierarchy or system catalog hierarchy. |
| Catalog | `catalog list` / `catalog create --name <name>` / `catalog info --catalog-id <id>` / `catalog update --catalog-id <id> --name <name>` / `catalog delete --catalog-id <id>` | List, create, inspect, rename, or delete catalogs. |
| Database | `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>` | Manage databases within a catalog. |
| Table | `catalog create-table --database-id <id> --name <name> --json-file <schema.json>` / `catalog table-info --table-id <id>` / `catalog preview-table --table-id <id>` | Create tables, inspect schemas, or preview table rows. |
| Table export & cleanup | `catalog download-table --table-id <id> --output <path>` / `catalog truncate-table --table-id <id>` / `catalog delete-table --table-id <id>` | Export table data to a local file, truncate rows, or drop a table. |

To inspect the JSON schema payload accepted by `create-table` offline, run `moi-cli schema catalog create-table`.

:::{warning}
`catalog truncate-table`, `delete-table`, `delete-database`, and `catalog delete` immediately clear or drop target data objects. Always verify the full resource path, numeric ID, and workspace first with `catalog table-full-path --table-id <id>` or `catalog database-info --database-id <id>`.
:::

<span id="管理卷（volume）与文件上传下载"></span>

## Manage volumes and file uploads/downloads

Placing a local file into a database volume is a two-step workflow: upload the file bytes with `catalog upload` to obtain a `file_id`, then attach that `file_id` to the target volume with `catalog create-file`:

```bash
# 1) Create a volume inside a database (skip if using an existing volume)
moi-cli -auth pat -o catalog create-volume \
  --database-id "$DATABASE_ID" \
  --name "raw_reports"

# 2) Stage the local file and extract the returned file_id
FILE_ID="$(
  moi-cli -auth pat -o catalog upload --file-path ./sales_2026.csv \
    | jq -er '.file_id // .id'
)"

# 3) Attach the uploaded file reference to the target volume and list files
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) Download the file from the volume to a local path
moi-cli -auth pat catalog download-file \
  --volume-id "$VOLUME_ID" \
  --file-id "$FILE_ID" \
  --output ./downloaded_sales_2026.csv
```

Common volume, folder, and file subcommands:

| Subcommand and key flags | Description |
| --- | --- |
| `catalog create-volume --database-id <id> --name <name>` / `volume-info --volume-id <id>` / `volume-full-path --volume-id <id>` / `delete-volume --volume-id <id>` | Create, inspect full path, or delete a volume. |
| `catalog create-folder --parent-volume-id <vol-id> --database-id <db-id> --name <name>` / `delete-folder --folder-id <id>` / `clean-folder --folder-id <id>` | Create, empty, or delete folders inside a volume. |
| `catalog upload --file-path <path> [--filename <name>]` / `catalog upload-private --file-path <path>` | Upload workspace or private files and obtain a file ID. |
| `catalog create-file --volume-id <vol-id> --file-ids <id1,id2>` | Register uploaded file IDs inside the target volume. |
| `catalog files --volume-id <vol-id> [--name <kw>] [--extensions <ext>]` / `file-info --file-id <id>` | List volume files with pagination or inspect single-file metadata. |
| `catalog download-file --volume-id <vol-id> --file-id <id> [--as-zip] --output <path>` | Download a volume file to a local output path. |
| `catalog delete-file --volume-id <vol-id> --file-id <id>` / `delete-file-ref --volume-id <vol-id> --file-ids <ids>` | Delete a volume file or detach file references. |

<span id="查询数据资产与运行-nl2sql"></span>
<span id="数据资产和高级文件操作"></span>

## Query data assets and run NL2SQL

| Subcommand and key flags | Description |
| --- | --- |
| `catalog data-asset --asset-id <id>` / `catalog batch-get-data-assets --raw-file-ids <ids>` | Inspect data assets by asset ID or batch raw file IDs. |
| `catalog file-data-asset --file-id <id>` / `catalog file-artifact --file-id <id>` / `catalog batch-resolve-file-artifacts --file-ids <ids>` | Resolve associated data assets and derived artifacts from file IDs. |
| `catalog run-nl2sql --database-id <id> --sql <query-text>` | Submit a natural-language-to-SQL request scoped to a database. |

<span id="跨工作区数据发布与订阅（data-share）"></span>
<span id="数据发布与数据订阅"></span>
<span id="检查发布范围"></span>

## Cross-workspace data publishing and subscriptions (`data-share`)

`data-share` establishes read-only sharing relationships across workspaces without copying or deleting underlying source tables.

### Publisher: verify source tables and target workspaces, then create a publication

```bash
# 1) Inspect publishable source tables, check name availability, and verify target workspace names
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) Create the publication and confirm its summary
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
```

### Subscriber: list available shares and mount a local subscription database

Switch to the receiving workspace to list available publications and subscribe:

```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 sharing subcommand summary:

| Subcommand and key flags | Description |
| --- | --- |
| `data-share source-tables --source-database-id <db-id>` | List tables eligible for publishing in a source database. |
| `data-share check-publish-name --name <name>` | Check whether a publication name is available without creating a resource. |
| `data-share resolve-workspace-names --ids <ws-ids>` / `workspace-names-result --ids <ws-ids>` | Resolve and verify target workspace IDs against workspace names. |
| `data-share create-publish` / `update-publish --publish-id <id>` / `delete-publish --publish-id <id>` | Create, update table/workspace scope, or delete a data publication. |
| `data-share publishes` / `publish-summary` | List workspace publications and view publication summary counts. |
| `data-share subscriptions [--status <status>]` / `subscribe --subscription-id <id> --sub-name <name>` / `unsubscribe --subscription-id <id>` | List incoming shares, mount a subscription database, or unsubscribe. |

<span id="限制和注意事项"></span>

## Limitations and notes

- `catalog upload` and `catalog upload-private` enforce a default `64 MiB` per-command memory read cap; pass `--max-upload-bytes <bytes>` when uploading larger files (see [Command Reference](../command-reference.md)).
- Private file uploads (`upload-private`, `upload-private-file`, `upload-private-bytes`) remain governed by workspace role permissions and volume access boundaries.
- Running `data-share delete-publish` or `data-share unsubscribe` revokes cross-workspace table visibility immediately; confirm that downstream dashboards, SQL queries, and workflows no longer depend on the shared database beforehand.
