跳到主要内容

管理 Snapshot

申请开通

本指南介绍如何创建和管理 Snapshot，包括：

说明

此功能仅限 Dedicated 集群使用。

创建 Snapshot​

创建 Snapshot 前，建议停止向目标 Collection 写入数据，并调用 flush()，以避免潜在的数据丢失。

说明

调用 flush() 不是强制要求，但强烈建议执行，以避免数据丢失。如果跳过该操作，Snapshot 只会包含已经 flush 的数据。

为 Snapshot 命名时，请使用清晰、描述性强的名称，例如 "daily_backup_20240101" 或 "v2.1_production_release"，并避免使用 "backup1"、"test" 这类泛泛的名称。请合理使用 Snapshot 名称，以区分不同版本、环境和阶段的 Snapshot。

以下代码示例假设你已经有一个名为 my_collection 的 Collection。

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

# Recommended: Flush data before creating snapshot to ensure all data is included
client.flush(collection_name="my_collection")

# Create snapshot for entire collection
client.create_snapshot(
    collection_name="my_collection",
    snapshot_name="backup_20240101",
    description="Daily backup for January 1st, 2024"
)

列出 Snapshot​

你可以列出现有 Snapshot 的名称。

python
# List all snapshots for a collection
snapshots = client.list_snapshots(
    collection_name="my_collection"
)

查看 Snapshot 详情​

你可以获取指定 Snapshot 的详细信息。

python
snapshot_info = client.describe_snapshot(
    snapshot_name="backup_20240101",
    collection_name="my_collection",
)

print(f"Snapshot name: {snapshot_info.name}")
print(f"Collection: {snapshot_info.collection_name}")
print(f"Created: {snapshot_info.create_ts}")
print(f"Description: {snapshot_info.description}")

Pin/unpin Snapshot 数据​

恢复期间，你可以 pin 一个 Snapshot，以临时保护其底层数据不被垃圾回收；也可以 unpin 该 Snapshot，以释放这些数据。

你还可以为 pin 操作设置生存时间（TTL），使被 pin 的数据在 TTL 到期后自动释放。

python
pin_id = client.pin_snapshot_data(
    snapshot_name="backup_20240101",
    collection_name="my_collection",
    ttl_seconds=3600,
)

client.unpin_snapshot_data(
    pin_id=pin_id
)

恢复 Snapshot​

你可以将 Snapshot 恢复到一个新的 Collection。该操作是异步的，并会返回一个任务 ID，用于跟踪恢复进度。

恢复过程使用 copy-segment 机制，而不是数据导入，因此效率更高，原因如下：

  • 直接从 Snapshot 存储中复制 Segment 文件（binlogs、deltalogs、Index 文件）

  • 保留 Field ID 和 Index ID，以确保与现有数据文件兼容

  • 避免数据重写和 Index 重建，从而显著缩短恢复时间

  • 相比传统 Backup 和 Restore 方法，性能提升 10 到 100 倍

如需恢复 Snapshot，请执行以下操作：

python
# Restore snapshot to new collection
job_id = client.restore_snapshot(
    snapshot_name="backup_20240101",
    source_collection_name="my_collection",
    target_collection_name="restored_collection",
)

有关如何监控恢复任务进度的详细信息，请参阅 获取恢复状态。

删除 Snapshot​

如果不再需要某个 Snapshot，你可以将其删除。建议定期删除旧 Snapshot，以节省存储空间。

python
client.drop_snapshot(
    snapshot_name="backup_20240101",
    collection_name="my_collection"
)

列出恢复任务​

你可以使用该 API 获取目标 Collection 已创建的 Snapshot 列表。

python
# List all restore jobs
jobs = client.list_restore_snapshot_jobs()

for job in jobs:
    print(f"Job {job.job_id}: {job.snapshot_name} -> Collection {job.collection_name}")
    print(f"  State: {job.state}, Progress: {job.progress}%")

# List restore jobs for a specific collection
jobs = client.list_restore_snapshot_jobs(collection_name="my_collection")

获取恢复状态​

获得恢复任务 ID 后，你可以使用该 ID 查询恢复进度。

python
state = client.get_restore_snapshot_state(job_id=12345)

print(f"Job ID: {state.job_id}")
print(f"Snapshot Name: {state.snapshot_name}")
print(f"Collection: {state.collection_name}")
print(f"State: {state.state}")
print(f"Progress: {state.progress}%")
if state.state == "RestoreSnapshotFailed":
    print(f"Failure Reason: {state.reason}")
print(f"Time Cost: {state.time_cost}ms")
Ctrl I