管理快照Compatible with Milvus 3.0.x

在本指南中，您將學習如何建立和管理快照，包括

• 建立快照、
• 列出快照，
• 描述快照，
• 固定／取消固定快照資料，
• 還原快照，
• 刪除快照，
• 列出還原工作，以及
• 取得還原狀態。

建立快照

在建立快照之前，建議您停止向目標集合寫入資料，並呼叫 `flush() ` 以避免可能的資料遺失。

為快照命名時，請使用清晰且具描述性的名稱，例如"daily_backup_20240101" 或"v2.1_production_release" ，並避免使用通用術語，例如"backup1" 和"test" 。請明智地使用快照名稱，以區分不同版本、環境和階段的快照。

以下程式碼範例假設您已經有一個名為my_collection 的集合。

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

# 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"
)

// java

import (
    "context"
    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

client, err := milvusclient.New(context.Background(), &milvusclient.ClientConfig{
    Address: "localhost:19530",
    Token: "root:Milvus",
})

// Recommended: Flush data before creating snapshot to ensure all data is included
err = client.Flush(context.Background(), milvusclient.NewFlushOption("my_collection"))
if err != nil {
    log.Fatal(err)
}

// Create snapshot
createOpt := milvusclient.NewCreateSnapshotOption("backup_20240101", "my_collection").
    WithDescription("Daily backup for January 1st, 2024")

err = client.CreateSnapshot(context.Background(), createOpt)

// node.js

# restful

列出快照

您可以列出現有快照的名稱。

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

// java

// List snapshots for collection
listOpt := milvusclient.NewListSnapshotsOption().
    WithCollectionName("my_collection")

snapshots, err := client.ListSnapshots(context.Background(), listOpt)

// node.js

# bash

檢視快照詳細資訊

您可以取得特定快照的詳細資訊。

snapshot_info = client.describe_snapshot(
    snapshot_name="backup_20240101",
    include_collection_info=True
)

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

// java

describeOpt := milvusclient.NewDescribeSnapshotOption("backup_20240101")
resp, err := client.DescribeSnapshot(context.Background(), describeOpt)

fmt.Printf("Snapshot ID: %d\n", resp.GetSnapshotInfo().GetId())
fmt.Printf("Collection: %s\n", resp.GetSnapshotInfo().GetCollectionName())

// node.js

# restful

固定／解除固定快照資料

在還原過程中，您可以將快照固定，以暫時保護其底層資料免於被垃圾回收；亦可解除固定以釋放資料。

您亦可為固定操作設定有效期限 (TTL)，以便在期限屆滿時釋放已固定的資料。

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
)

// java

pinID, err := client.PinSnapshotData(
    context.Background(),
    milvusclient.NewPinSnapshotDataOption("backup_20240101", "my_collection").WithTTL(3600),
)
if err != nil {
    log.Fatal(err)
}

defer func() {
    _ = client.UnpinSnapshotData(
        context.Background(),
        milvusclient.NewUnpinSnapshotDataOption(pinID),
    )
}()

// Do work with pinned snapshot data.

// node.js

# restful

還原快照

您可以將快照還原至新的集合。此操作為非同步，並會傳回一個工作 ID 以供追蹤還原進度。

還原過程採用「複製區段」機制而非資料匯入，此方式更為高效，因為它

• 直接從快照儲存空間複製區段檔案（二進位日誌、增量日誌、索引檔案）
• 保留欄位 ID 和索引 ID，以確保與現有資料檔案的相容性
• 避免資料重寫與索引重建，從而顯著縮短還原時間，並
• 相較於傳統的備份與還原方法，效能提升 10 至 100 倍

要還原快照，請依下列步驟操作：

# Restore snapshot to new collection
job_id = client.restore_snapshot(
    snapshot_name="backup_20240101",
    collection_name="restored_collection",
)

// java

restoreOpt := milvusclient.NewRestoreSnapshotOption(
    "backup_20240101",
    "restored_collection"
)

jobID, err := client.RestoreSnapshot(context.Background(), restoreOpt)
if err != nil {
    log.Fatal(err)
}

// node.js

# restful

有關監控還原工作進度的詳細資訊，請參閱「取得還原狀態」。

刪除快照

若快照已無使用需求，您可以刪除該快照。建議您定期刪除舊快照以節省儲存空間。

client.drop_snapshot(
    snapshot_name="backup_20240101"
)

// java

dropOpt := milvusclient.NewDropSnapshotOption("backup_20240101")
err := client.DropSnapshot(context.Background(), dropOpt)

// node.js

# restful

列出還原工作

您可以使用此 API 取得已為目標集合建立的快照清單。

# 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_id}")
    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")

// java

// List all restore jobs
listOpt := milvusclient.NewListRestoreSnapshotJobsOption()
jobs, err := client.ListRestoreSnapshotJobs(context.Background(), listOpt)
if err != nil {
    log.Fatal(err)
}

for _, job := range jobs {
    fmt.Printf("Job %d: %s -> Collection %d\n",
        job.GetJobId(), job.GetSnapshotName(), job.GetCollectionId())
    fmt.Printf("  State: %s, Progress: %d%%\n",
        job.GetState(), job.GetProgress())
}

// List restore jobs for a specific collection
listOpt = milvusclient.NewListRestoreSnapshotJobsOption().
    WithCollectionName("my_collection")
jobs, err = client.ListRestoreSnapshotJobs(context.Background(), listOpt)

// node.js

# restful

取得還原狀態

取得還原工作 ID 後，即可使用該 ID 查詢還原進度。

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 ID: {state.collection_id}")
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")

// java

stateOpt := milvusclient.NewGetRestoreSnapshotStateOption(12345)
state, err := client.GetRestoreSnapshotState(context.Background(), stateOpt)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Job ID: %d\n", state.GetJobId())
fmt.Printf("Snapshot Name: %s\n", state.GetSnapshotName())
fmt.Printf("Collection ID: %d\n", state.GetCollectionId())
fmt.Printf("State: %s\n", state.GetState())
fmt.Printf("Progress: %d%%\n", state.GetProgress())
if state.GetState() == milvuspb.RestoreSnapshotState_RestoreSnapshotFailed {
    fmt.Printf("Failure Reason: %s\n", state.GetReason())
}
fmt.Printf("Time Cost: %dms\n", state.GetTimeCost())

// node.js

# restful