Export and Import Data with Export/Import V2

Export/Import V2 creates portable snapshots of GreptimeDB data. Use it to back up data, restore data, or migrate data between GreptimeDB instances.

An Export/Import V2 snapshot contains schema metadata, a manifest, and data files. Data files are split into chunks so interrupted export and import jobs can resume from the previous progress.

This guide uses the following commands:

• greptime cli data export-v2 create to create a snapshot
• greptime cli data export-v2 verify to verify a snapshot
• greptime cli data export-v2 list to list snapshots under a parent location
• greptime cli data export-v2 delete to delete a snapshot
• greptime cli data import-v2 to import from a snapshot

Prerequisites

Before using Export/Import V2, make sure that:

• The GreptimeDB HTTP endpoint is reachable, for example 127.0.0.1:4000.
• You have a greptime binary that includes the cli data export-v2 and cli data import-v2 commands.
• The snapshot storage location is readable and writable by both the CLI client and the GreptimeDB server.

For remote object storage, explicitly enable one supported backend and provide the backend options. Export/Import V2 supports S3-compatible storage, Alibaba Cloud OSS, Google Cloud Storage, and Azure Blob Storage. For example, use --s3 with --s3-region for S3-compatible storage.

For file:// snapshots, the path must be accessible from the GreptimeDB server as well as the CLI client. This usually means running the CLI on the same host as a standalone server, or mounting the same filesystem path into the GreptimeDB server. The parent directory of the snapshot must exist before you create the snapshot. For remote, Kubernetes, or distributed deployments, use object storage such as S3 or MinIO instead of a local file:// path.

The GreptimeDB server writes snapshot data files with COPY DATABASE ... TO, so a file:// snapshot path must also be inside the server's copy root, which is storage.copy_root and defaults to <storage.data_home>/copy. The server rejects a path outside the copy root. Object storage snapshots are not subject to the copy root, because the server writes them directly to the object store. See Migrate Local SQL File Access for details.

note

The snapshot URI, such as s3://my-bucket/snapshots/prod, identifies the snapshot location, including the bucket. The object store options, such as --s3-region and --s3-endpoint, configure how the CLI connects to the backend. --s3-bucket and --s3-root do not change where the snapshot is read or written; the URI is authoritative. Pass the same connection options to create, verify, import, list, and delete commands.

Quick start with local filesystem

The examples in this guide use a source standalone instance at 127.0.0.1:4000 and a separate restore target at 127.0.0.1:4100. Prepare a clean target; import does not clear existing data. If both instances run on the same host, use separate data directories and listening ports. Replace these addresses with your own source and target endpoints.

For local filesystem snapshots, the CLI, source, and target must all access the same files.

The examples in this guide store snapshots under /tmp/greptime-snapshots. Set this directory as the copy root in both instances' GreptimeDB configuration files and restart both instances:

[storage]
copy_root = "/tmp/greptime-snapshots"

Create the parent directory so that the CLI and both instances can access it:

mkdir -p /tmp/greptime-snapshots

Create a snapshot:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/demo

Verify the snapshot before restoring it:

greptime cli data export-v2 verify \
  --snapshot file:///tmp/greptime-snapshots/demo

Import from the snapshot:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/demo

By default, export and import use the greptime catalog. Add --catalog <catalog> if you need another catalog.

Export to remote object storage

Export/Import V2 can store snapshots in AWS S3, S3-compatible services such as MinIO, Alibaba Cloud OSS, Google Cloud Storage, and Azure Blob Storage. The examples below use the S3 backend because S3 and MinIO are common choices. For other object stores, use the corresponding backend flag and options described in Supported storage backends.

S3 or MinIO

Use the S3 backend for AWS S3 and S3-compatible services such as MinIO.

S3-compatible endpoint

For MinIO, pass --s3-endpoint. Set S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY in your shell to credentials for your bucket before running these examples:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to s3://greptime/snapshots/local-test \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id "${S3_ACCESS_KEY_ID}" \
  --s3-secret-access-key "${S3_SECRET_ACCESS_KEY}" \
  --s3-endpoint http://127.0.0.1:9000

Use the same storage options when verifying, importing, listing, or deleting the snapshot:

greptime cli data export-v2 verify \
  --snapshot s3://greptime/snapshots/local-test \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id "${S3_ACCESS_KEY_ID}" \
  --s3-secret-access-key "${S3_SECRET_ACCESS_KEY}" \
  --s3-endpoint http://127.0.0.1:9000

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from s3://greptime/snapshots/local-test \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id "${S3_ACCESS_KEY_ID}" \
  --s3-secret-access-key "${S3_SECRET_ACCESS_KEY}" \
  --s3-endpoint http://127.0.0.1:9000

For AWS S3, use the same --s3 options but omit --s3-endpoint unless you use a custom endpoint. If your environment uses instance profiles or another credential provider, explicit access keys may not be required. The S3 backend still requires --s3 and --s3-region.

Use Metric packed snapshots

Packed export groups small Metric logical tables into shared objects and can reduce repeated scans and object-store requests. Each table retains its schema. Large logical tables and ordinary tables use separate objects. Packing can increase memory usage.

Ordinary Metric table export writes each logical table separately and supports Parquet, CSV, and JSON. Use a CLI and servers that support packed snapshots. The CLI checks for packed-export capability before creating or resuming a packed snapshot.

With the local copy root configured as in the quick start, export the public schema with --pack-metric-data to enable shared Metric scans and packed output:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/metric-packed \
  --schemas public \
  --pack-metric-data

For S3 or MinIO, add --pack-metric-data to the remote export example, using a new snapshot prefix. The storage options and copy-root requirements are unchanged. Packed export supports only Parquet, the default --format; CSV and JSON require ordinary export.

Verify and import with the existing commands; import selects the layout from the manifest and needs no packed-mode flag:

greptime cli data export-v2 verify \
  --snapshot file:///tmp/greptime-snapshots/metric-packed

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/metric-packed

The target must support packed import; otherwise, import stops before executing DDL or writing data.

Snapshot version compatibility

The v2 in the command names is separate from the manifest version:

Export selection	Manifest version	Data layout
Default export	1	Standalone files
--pack-metric-data (data export)	2	Packed and standalone Parquet objects with indexes
--schema-only	1	No data files

--schema-only still produces manifest v1 when combined with --pack-metric-data. This combination does not require packed-data capability.

Use an importer that supports manifest v2 to restore packed snapshots. It also reads v1 snapshots; older v1-only importers reject v2 before executing DDL.

Export selected schemas

By default, export-v2 create exports every schema except information_schema. This includes the greptime_private schema, and importing such a snapshot restores greptime_private as well. To exclude it, list the schemas you want explicitly with --schemas.

Export only selected schemas with --schemas. You can pass a comma-separated list:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/observability \
  --schemas public,metrics

Or pass the option multiple times:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/observability \
  --schemas public \
  --schemas metrics

When importing, --schemas selects a subset from the snapshot:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/observability \
  --schemas public

If you request a schema that is not in the snapshot, the import fails.

Export schema only

Use --schema-only to export table definitions without data:

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/schema-only \
  --schema-only

Importing a schema-only snapshot restores the schema but does not import data chunks:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/schema-only

Choose the data file format

Use --format to choose the data file format. Supported values are parquet, csv, and json. The default is parquet.

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/demo-csv \
  --format csv

The format is recorded in the snapshot manifest. import-v2 reads the format from the manifest and applies it automatically, so you do not need to specify the format again when importing.

Export by time range and chunk window

Use a bounded time range and a chunk window for large datasets. Export/Import V2 creates one or more data chunks for each schema in the range.

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to s3://greptime/snapshots/prod-2026-06 \
  --start-time 2026-06-01T00:00:00Z \
  --end-time 2026-07-01T00:00:00Z \
  --chunk-time-window 1d \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id "${S3_ACCESS_KEY_ID}" \
  --s3-secret-access-key "${S3_SECRET_ACCESS_KEY}" \
  --s3-endpoint http://127.0.0.1:9000

--chunk-time-window requires both --start-time and --end-time. For packed export, the start must precede the end.

Chunks are created by time window. For example, a 15-minute range with --chunk-time-window 5m creates 3 chunks. During import, data tasks are scheduled per chunk and per schema. If the snapshot contains 3 chunks and 2 schemas with data, import schedules 6 data tasks.

For the default standalone-file layout, snapshot data files are organized by schema and chunk. For example, a multi-chunk snapshot can contain paths such as:

data/logs/1/app_logs.parquet
data/logs/2/app_logs.parquet
data/logs/3/app_logs.parquet
data/public/1/host_metrics.parquet
data/public/2/host_metrics.parquet
data/public/3/host_metrics.parquet

Choose the chunk window based on the data volume and density:

• Use a larger window for small or sparse datasets to avoid too many small chunks.
• Use a smaller window for large datasets to keep each chunk manageable.
• Start with 1d and adjust after checking export duration and chunk sizes.

Tune parallelism

Export has two parallelism options:

• --parallelism controls server-side COPY DATABASE parallelism per schema per chunk. The default is 1.
• --chunk-parallelism controls how many export chunks the client runs concurrently. The default is 1 and the valid range is 1..=64.

Import uses:

• --task-parallelism to control how many import data tasks the client runs concurrently. The default is 1 and the valid range is 1..=64.

Increase these values gradually and monitor GreptimeDB, object storage, and network resource usage.

Resume an interrupted export or import

warning

An HTTP timeout or a stopped CLI does not prove that the server request or storage writes have stopped. Before resuming, deleting incomplete output, or using --force, confirm that the original export/import request and its writes have ended. Do not run overlapping attempts against the same snapshot or restore destination.

For export:

• If the target snapshot does not exist, export-v2 create creates it.
• If the target snapshot already exists, the same command resumes from existing progress.
• Completed chunks are skipped. Failed or pending chunks are retried.
• Use --force only when you want to delete the existing snapshot and recreate it.

greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/demo

Resume retains the snapshot layout. For packed snapshots, you can omit --pack-metric-data when resuming. The source server must still support packed export. To switch a v1 snapshot to packed layout, create a new snapshot at a different location.

Retry cleans incomplete output and keeps completed chunks. Unrecognized files in an incomplete chunk cause cleanup to fail. Keep source data and table definitions unchanged across attempts.

For import, progress is stored in a state file while the import is running. By default, the state file is under ~/.greptime/import_state. Override it with --state-path when you want an explicit state location:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/demo \
  --state-path /tmp/greptime-import-demo.state

--dry-run does not create an import state file. A real import keeps the state file if it fails or is interrupted, so the next run can resume completed data tasks. After a successful import, import-v2 automatically deletes the state file because there is no remaining work to resume. A .lock file with the same prefix can remain; it is a lock file, not the import state content.

Import failures leave completed DDL and inserted rows in the target. Resume can re-execute DDL and unfinished schema/chunk data tasks, including rows already written. Check the target before retrying.

For a fresh restore, first confirm the original requests have ended and prepare a clean destination, then use a new --state-path or remove the old state file. Changing the state file alone does not remove partially restored data.

Dry-run an import

Use --dry-run to validate the snapshot and import plan without executing DDL or importing data:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/demo \
  --dry-run

Dry-run is useful before a production migration or restore.

Verify, list, and delete snapshots

Verify a snapshot:

greptime cli data export-v2 verify \
  --snapshot file:///tmp/greptime-snapshots/demo

verify checks snapshot structure and completeness, including packed indexes and object byte ranges. It does not compare data values or verify content checksums. Validate restored data separately.

List snapshots under a parent location to see completed chunk counts and the manifest-derived status (complete, incomplete, schema-only, or unsupported):

greptime cli data export-v2 list \
  --location file:///tmp/greptime-snapshots

Delete a snapshot:

greptime cli data export-v2 delete \
  --snapshot file:///tmp/greptime-snapshots/demo

For non-interactive deletion, pass --no-confirm:

greptime cli data export-v2 delete \
  --snapshot s3://greptime/snapshots/local-test \
  --no-confirm \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id "${S3_ACCESS_KEY_ID}" \
  --s3-secret-access-key "${S3_SECRET_ACCESS_KEY}" \
  --s3-endpoint http://127.0.0.1:9000

Authentication, timeout, proxy, and progress

If the GreptimeDB instance has basic authentication enabled, pass credentials with --auth-basic <username>:<password>.

The CLI request timeout defaults to 60s. Set it with --timeout, for example --timeout 5m, allowing enough time for a data task. A timeout does not confirm cancellation; follow the resume precautions before retrying.

For commands that connect to the GreptimeDB HTTP endpoint, such as export-v2 create and import-v2, use --proxy to set an HTTP proxy, or --no-proxy to disable proxy usage:

greptime cli data import-v2 \
  --addr 127.0.0.1:4100 \
  --from file:///tmp/greptime-snapshots/demo \
  --no-proxy

Long-running create and import commands support --progress to control progress output:

• auto: show an interactive bar on a TTY, otherwise log progress. This is the default.
• always: always emit progress; it uses a bar on a TTY and lightweight logs otherwise.
• never: never emit progress.

Supported storage backends

Export/Import V2 supports local filesystem snapshots and remote object storage snapshots.

For remote object storage, enable exactly one backend:

• --s3 for AWS S3 or S3-compatible storage such as MinIO
• --oss for Alibaba Cloud OSS
• --gcs for Google Cloud Storage
• --azblob for Azure Blob Storage

Common S3 options are:

Option	Description
--s3-bucket	S3 bucket name. Does not affect the snapshot location; the bucket in the snapshot URI is used.
--s3-region	S3 region. Required for S3.
--s3-access-key-id	Access key ID. Optional when the environment provides credentials.
--s3-secret-access-key	Secret access key. Optional when the environment provides credentials.
--s3-endpoint	Custom S3-compatible endpoint, such as a MinIO endpoint.
--s3-enable-virtual-host-style	Enable virtual-hosted-style requests.
--s3-disable-ec2-metadata	Disable EC2 metadata service credential lookup.

Troubleshooting

Failed to connect to /v1/sql

Check that GreptimeDB is running and that --addr points to the HTTP endpoint:

curl http://127.0.0.1:4000/health

file:// path is outside the configured copy root

If export-v2 create fails with an error such as the following, the snapshot path is outside the server's copy root:

Local filesystem path '/tmp/greptime-snapshots/demo/data/greptime_private/1/' is outside the configured copy root or is unsafe

Set storage.copy_root to a directory that contains the snapshot path, or use a snapshot path under <storage.data_home>/copy. See Migrate Local SQL File Access for details.

The failed run leaves a partial snapshot on disk, and export-v2 verify reports the failed chunk. After fixing the configuration, run the same export-v2 create command again to resume, or pass --force to recreate the snapshot.

--chunk-time-window fails validation

--chunk-time-window requires both --start-time and --end-time. For packed export, the start must precede the end. Add a bounded time range or remove --chunk-time-window.

S3 or MinIO reports NoSuchBucket or NoSuchKey

Check that:

• The bucket and path in the snapshot URI are correct. --s3-bucket does not change the snapshot location.
• --s3-endpoint is set for MinIO or other S3-compatible services. Without it, the CLI sends requests to the public AWS S3 endpoint for --s3-region, which usually shows up as a long hang or a 301 response rather than a clear configuration error.
• The credentials can read and write the snapshot location.
• You pass the same storage options to create, verify, import, list, and delete commands.

Import skips data unexpectedly

Import resumes from its state file. If a previous import marked tasks as completed, a later run with the same state identity may skip them. Use an explicit --state-path for each restore operation, or remove the old state file after confirming it is safe.

A requested schema is not found

When using --schemas during import, make sure the schema exists in the snapshot. Use export-v2 verify first and check the snapshot contents.

Verification fails

Do not import a snapshot that fails verification. The snapshot may be incomplete or corrupted. Re-run the export with the same command to resume missing chunks, or recreate the snapshot with --force if you intentionally want to discard the existing snapshot.

Limitations

• Export/Import V2 snapshots are not the same format as the legacy export/import output.
• Keep the selected source data and table definitions stable throughout export and any resume. This is not a transactionally consistent online backup across tables or chunks. Keep snapshot files unchanged during import and avoid concurrent changes to the target tables.
• For packed export, each data write or multipart part is at most 8 MiB. This is not a size limit on the packed object or logical table.
• Schema filtering is schema-level. Table-level filtering is not covered by this command.
• Time-range chunking is designed for time-series data. Sparse data may need a larger chunk window.
• Schema-only snapshots do not contain data files.
• Large migrations require careful tuning of chunk window, parallelism, object storage throughput, and GreptimeDB resources.