使用 Export/Import V2 导出和导入数据

Export/Import V2 会创建可移植的 GreptimeDB 数据快照。你可以使用它备份数据、恢复数据，或在 GreptimeDB 实例之间迁移数据。

V2 快照包含 schema 元数据、manifest 和数据文件。数据文件会被拆分为 chunks，因此中断的导出和导入任务可以从之前的进度继续执行。

本指南使用以下命令：

• greptime cli data export-v2 create：创建快照
• greptime cli data export-v2 verify：验证快照
• greptime cli data export-v2 list：列出父路径下的快照
• greptime cli data export-v2 delete：删除快照
• greptime cli data import-v2：从快照导入数据

前置条件

使用 Export/Import V2 之前，请确认：

• GreptimeDB HTTP endpoint 可访问，例如 127.0.0.1:4000。
• 你的 greptime binary 包含 cli data export-v2 和 cli data import-v2 命令。
• CLI client 和 GreptimeDB server 都能读写快照存储位置。

对于远程对象存储，仅有快照 URI 还不够。你还需要显式启用一个受支持的存储后端，并传入该后端的连接选项。Export/Import V2 支持 S3-compatible 存储、阿里云 OSS、Google Cloud Storage 和 Azure Blob Storage。例如，对于 S3-compatible 存储，需要同时使用 --s3 和 --s3-region。

对于 file:// 快照，路径必须同时能被 GreptimeDB server 和 CLI client 访问。通常这意味着 CLI 与 standalone server 运行在同一台主机上，或者将同一个文件系统路径挂载到 GreptimeDB server 中。创建快照之前，快照的父目录必须已经存在。对于远程、Kubernetes 或分布式部署，请使用 S3 或 MinIO 等对象存储，而不是本地 file:// 路径。

GreptimeDB server 通过 COPY DATABASE ... TO 写入快照数据文件，因此 file:// 快照路径还必须位于 server 的 copy root 内，即 storage.copy_root，默认为 <storage.data_home>/copy。位于 copy root 之外的路径会被 server 拒绝。对象存储快照不受 copy root 限制，因为 server 会直接把数据写入对象存储。详情请参阅迁移本地 SQL 文件访问。

备注

快照 URI（例如 s3://my-bucket/snapshots/prod）标识快照位置，其中包括 bucket。对象存储选项（例如 --s3-region 和 --s3-endpoint）配置 CLI 如何连接到对应后端。--s3-bucket 和 --s3-root 不会改变快照的读写位置，以 URI 为准。请在 create、verify、import、list 和 delete 命令中传入相同的连接选项。

使用本地文件系统快速开始

只有在 CLI client 和 GreptimeDB server 共享同一路径时，才应使用本地文件系统快照。例如，对于本地 standalone server，如果 CLI 在同一台主机上运行，这种方式可以工作。

本指南中的示例把快照存放在 /tmp/greptime-snapshots 下。请在 GreptimeDB 配置文件中把该目录设置为 server 的 copy root，然后重启 server：

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

也可以保留默认的 copy root，改用 <storage.data_home>/copy 下的快照路径，例如 file:///path/to/data_home/copy/demo。

创建父目录，并确保 server 和 CLI 都能访问它：

mkdir -p /tmp/greptime-snapshots

创建快照：

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

恢复之前先验证快照：

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

从快照导入：

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

默认情况下，导出和导入使用 greptime catalog。如果需要使用其他 catalog，请添加 --catalog <catalog>。

导出到远程对象存储

Export/Import V2 可以将快照存储到 AWS S3、MinIO 等 S3-compatible 服务、阿里云 OSS、Google Cloud Storage 和 Azure Blob Storage。下面的示例使用 S3 backend，因为 S3 和 MinIO 是常见选择。对于其他对象存储，请使用 支持的存储后端 中对应的 backend flag 和选项。

S3 或 MinIO

对于 AWS S3 以及 MinIO 等 S3-compatible 服务，请使用 S3 backend。

S3-compatible endpoint

对于 MinIO，请传入 --s3-endpoint：

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 superpower_ci_user \
  --s3-secret-access-key superpower_password \
  --s3-endpoint http://127.0.0.1:9000

验证、导入、列出或删除快照时，也需要使用相同的存储选项：

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 superpower_ci_user \
  --s3-secret-access-key superpower_password \
  --s3-endpoint http://127.0.0.1:9000

greptime cli data import-v2 \
  --addr 127.0.0.1:4000 \
  --from s3://greptime/snapshots/local-test \
  --s3 \
  --s3-bucket greptime \
  --s3-region us-west-2 \
  --s3-access-key-id superpower_ci_user \
  --s3-secret-access-key superpower_password \
  --s3-endpoint http://127.0.0.1:9000

对于 AWS S3，请使用相同的 --s3 选项；除非使用自定义 endpoint，否则不要传 --s3-endpoint。如果你的环境使用 instance profile 或其他凭据提供机制，可能不需要显式传入 access key。S3 backend 仍然需要 --s3 和 --s3-region。

导出指定 schemas

默认情况下，export-v2 create 会导出除 information_schema 之外的所有 schema，其中包括 greptime_private schema，导入这样的快照时也会一并恢复 greptime_private。如果要排除它，请使用 --schemas 显式列出需要导出的 schemas。

使用 --schemas 只导出指定 schemas。可以传入逗号分隔的列表：

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

也可以多次传入该选项：

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

导入时，--schemas 会从快照中选择一个子集：

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

如果请求的 schema 不存在于快照中，导入会失败。

只导出 schema

使用 --schema-only 导出表定义，不导出数据：

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

导入 schema-only 快照会恢复 schema，但不会导入数据 chunks：

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

选择数据文件格式

使用 --format 选择数据文件格式。支持的值为 parquet、csv 和 json，默认值为 parquet。

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

格式会记录在快照的 manifest 中。import-v2 会从 manifest 中读取格式并自动应用，因此导入时不需要再次指定格式。

按时间范围和 chunk window 导出

对于大数据集，请使用有界时间范围和 chunk window。Export/Import V2 会为范围内的每个 schema 创建一个或多个数据 chunks。

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 superpower_ci_user \
  --s3-secret-access-key superpower_password \
  --s3-endpoint http://127.0.0.1:9000

--chunk-time-window 需要同时指定 --start-time 和 --end-time。

Chunks 会按时间窗口创建。例如，15 分钟的范围配合 --chunk-time-window 5m 会创建 3 个 chunks。导入时，数据任务按 chunk 和 schema 调度。如果快照包含 3 个 chunks，且有 2 个 schema 包含数据，则导入会调度 6 个数据任务。

快照数据文件也会按 schema 和 chunk 组织。例如，一个多 chunk 快照可能包含如下路径：

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

请根据数据量和数据密度选择 chunk window：

• 对于较小或稀疏的数据集，使用更大的 window，避免产生太多小 chunks。
• 对于较大的数据集，使用更小的 window，让每个 chunk 保持在可管理的大小。
• 可以先从 1d 开始，再根据导出耗时和 chunk 大小调整。

调整并行度

导出有两个并行度选项：

• --parallelism 控制每个 schema、每个 chunk 上 server-side COPY DATABASE 的并行度。默认值为 1。
• --chunk-parallelism 控制 client 同时运行多少个 export chunks。默认值为 1，有效范围是 1..=64。

导入使用：

• --task-parallelism 控制 client 同时运行多少个 import data tasks。默认值为 1，有效范围是 1..=64。

请逐步提高这些值，并监控 GreptimeDB、对象存储和网络资源使用情况。

恢复中断的导出或导入

Export/Import V2 设计上支持恢复中断的工作。

对于导出：

• 如果目标快照不存在，export-v2 create 会创建它。
• 如果目标快照已存在，同一条命令会从已有进度继续执行。
• 已完成的 chunks 会被跳过。失败或 pending 的 chunks 会重试。
• 只有在你想删除已有快照并重新创建时，才使用 --force。

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

中断后再次运行同一条命令即可继续。

对于导入，导入运行时进度会保存在 state 文件中。默认情况下，state 文件位于 ~/.greptime/import_state。如果希望使用显式的 state 文件位置，可以用 --state-path 覆盖：

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

--dry-run 不会创建 import state 文件。真正的导入如果失败或中断，会保留 state 文件，因此下一次运行可以恢复已完成的数据任务。导入成功后，import-v2 会自动删除 state 文件，因为已经没有需要恢复的剩余工作。相同前缀的 .lock 文件可能保留下来；它是锁文件，不是导入状态内容。

如果你确实想在失败或中断后从头重新运行导入，请使用不同的 --state-path，或在确认安全后删除之前的 state 文件。

Dry-run 导入

使用 --dry-run 验证快照和导入计划，但不执行 DDL，也不导入数据：

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

Dry-run 适合在生产迁移或恢复前使用。

验证、列出和删除快照

验证快照：

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

列出父路径下的快照：

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

删除快照：

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

对于非交互式删除，请传入 --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 superpower_ci_user \
  --s3-secret-access-key superpower_password \
  --s3-endpoint http://127.0.0.1:9000

认证、超时、代理和进度

如果 GreptimeDB 实例启用了 basic authentication，请使用 --auth-basic <username>:<password> 传入凭据。

使用 --timeout 设置请求超时时间，例如 --timeout 60s 或 --timeout 5m。

对于会连接 GreptimeDB HTTP endpoint 的命令，例如 export-v2 create 和 import-v2，可以使用 --proxy 设置 HTTP 代理，或使用 --no-proxy 禁用代理：

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

长时间运行的 create 和 import 命令支持使用 --progress 控制进度输出：

• auto：在 TTY 上显示交互式进度条，否则输出进度日志。这是默认值。
• always：始终输出进度；在 TTY 上使用进度条，否则输出轻量日志。
• never：不输出进度。

支持的存储后端

Export/Import V2 支持本地文件系统快照和远程对象存储快照。

对于远程对象存储，请只启用一个 backend：

• --s3：用于 AWS S3 或 MinIO 等 S3-compatible 存储
• --oss：用于阿里云 OSS
• --gcs：用于 Google Cloud Storage
• --azblob：用于 Azure Blob Storage

常用 S3 选项如下：

Option	Description
--s3-bucket	S3 bucket 名称。不影响快照位置，实际使用的是快照 URI 中的 bucket。
--s3-region	S3 region。使用 S3 时必填。
--s3-access-key-id	Access key ID。当环境提供凭据时可选。
--s3-secret-access-key	Secret access key。当环境提供凭据时可选。
--s3-endpoint	自定义 S3-compatible endpoint，例如 MinIO endpoint。
--s3-enable-virtual-host-style	启用 virtual-hosted-style 请求。
--s3-disable-ec2-metadata	禁用 EC2 metadata service 凭据查找。

故障排除

无法连接到 /v1/sql

检查 GreptimeDB 是否正在运行，以及 --addr 是否指向 HTTP endpoint：

curl http://127.0.0.1:4000/health

file:// 路径位于 copy root 之外

如果 export-v2 create 返回类似下面的错误，说明快照路径位于 server 的 copy root 之外：

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

请把 storage.copy_root 设置为包含该快照路径的目录，或者改用 <storage.data_home>/copy 下的快照路径。详情请参阅迁移本地 SQL 文件访问。

失败的运行会在磁盘上留下一个不完整的快照，export-v2 verify 会报告失败的 chunk。修正配置后，再次运行同一条 export-v2 create 命令即可继续；如果想重新创建快照，请传入 --force。

--chunk-time-window 校验失败

--chunk-time-window 需要同时指定 --start-time 和 --end-time。请添加有界时间范围，或移除 --chunk-time-window。

S3 或 MinIO 返回 NoSuchBucket 或 NoSuchKey

请检查：

• 快照 URI 中的 bucket 和路径是否正确。--s3-bucket 不会改变快照位置。
• 对于 MinIO 或其他 S3-compatible 服务，是否设置了 --s3-endpoint。如果没有设置，CLI 会把请求发往 --s3-region 对应的公有 AWS S3 endpoint，通常表现为长时间无响应或返回 301，而不是明确的配置错误。
• 凭据是否可以读写快照位置。
• create、verify、import、list 和 delete 命令是否传入了相同的存储选项。

Import 意外跳过数据

Import 会从 state 文件恢复。如果之前的导入已经将任务标记为 completed，后续使用同一个 state identity 运行时可能会跳过这些任务。请为每次恢复操作使用显式的 --state-path，或在确认安全后删除旧 state 文件。

请求的 schema 不存在

在导入时使用 --schemas 时，请确认该 schema 存在于快照中。请先使用 export-v2 verify，并检查快照内容。

验证失败

不要导入验证失败的快照。快照可能不完整或已损坏。请使用同一条命令重新运行导出，以恢复缺失的 chunks；如果你确实想丢弃已有快照并重新创建，请使用 --force。

限制

• Export/Import V2 快照与 legacy export/import 输出不是同一种格式。
• Schema filter 的粒度是 schema-level。该命令不覆盖 table-level filter。
• Time-range chunking 面向时间序列数据设计。稀疏数据可能需要更大的 chunk window。
• Schema-only 快照不包含数据文件。
• 大规模迁移需要仔细调优 chunk window、并行度、对象存储吞吐和 GreptimeDB 资源。