Import

Prerequisites

1. CLI installed and logged in (see setup skill).
2. Target collection must exist on the target cluster.

Commands Reference

Import Jobs

Start an Import Job

zilliz import start --collection <target-collection-name>
# Optional:
#   --cluster-id <target-cluster-id>
#   --project-id <project-id>
#   --region-id <region-id>
# Or use raw JSON: --body '{"files": [["s3://bucket/path/data.parquet"]]}'

List Imports

zilliz import list
# Optional:
#   --cluster-id <cluster-id>
#   --project-id <project-id>
#   --region-id <region-id>
#   --database <database-name>

Check Import Status

zilliz import status --job-id <import-job-id>
# Optional:
#   --cluster-id <cluster-id>
#   --project-id <project-id>
#   --region-id <region-id>

Import Stages

List Stages

zilliz stage list
# Optional: --project-id <filter-by-project-id>
# Pagination: --page-size <n> --page <n>
# Fetch all pages: --all

Create a Stage

zilliz stage create \
  --project-id <owning-project-id> \
  --region-id <cloud-region> \
  --stage-name <stage-name>

Delete a Stage

zilliz stage delete --stage-name <stage-name>

Apply

zilliz stage apply --stage-name <stage-name>
# Optional:
#   --project-id <project-id>
#   --region-id <region-id>
#   --cluster-id <target-cluster-id>
#   --path <stage-subpath>

Integration Setup

Import requires a cloud storage integration to access data files. The integration-id is configured in the Zilliz Cloud console under Project Settings > Integrations. Ensure the integration has read access to the source bucket and path.

Supported file formats: Parquet, JSON, CSV.

Stages vs. Direct Integrations

A stage is a named, project-scoped handle to a pre-uploaded set of files in managed cloud storage. Import jobs reference either:

• a customer-owned bucket via an integration (the original flow above), or
• a stage (zilliz stage create --project-id <id> --region-id <region> --stage-name <name>), which is preferable when the user wants Zilliz Cloud to host the staging bucket.

stage apply updates an existing stage in place; stage delete removes it (confirm with the user first -- pending import jobs referencing the stage will fail).

Import Targets

import start, import list, and import status accept either:

• --cluster-id <id> (legacy form, still supported), or
• --project-id <id> together with --region-id <region> (the server then resolves the target instance from the project + region pair).

You must supply exactly one of those two grouping forms -- the CLI rejects an import command that provides neither, or that provides --project-id without --region-id.

Guidance

• Import jobs run asynchronously. After starting a job, use import status to track progress.
• The data files must be accessible from Zilliz Cloud (either via a configured integration or via a stage).
• The collection schema must match the data file structure.
• When importing into a Vector Lake / on-demand-cluster setup, prefer the --project-id + --region-id form -- on-demand clusters do not have a stable single cluster ID to point at.