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 before running these commands.

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:

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>.

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:

# 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.

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.

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

# 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:

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.

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).

  • 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.

Last updated on