Snapshots

快照是專案根分支的即時擷取，包括結構及所有資料。 Lakebase 能即時建立快照，效能影響極低。把它們當作備份或還原點。

你可以在 Lakebase 應用程式中建立、還原和管理快照，或使用 Python SDK、Java SDK、Databricks CLI 或 curl 的快照 API 程式化操作。 Terraform 可以透過建立分支從快照還原。若操作多於一種方式可用，指令會以制表符形式一同顯示。

Note

自 2026 年 6 月 1 日起，Lakebase 的快照儲存需計費。請參閱快照儲存成本。

何時使用快照

快照對於定期備份或在進行結構變更或其他可能具破壞性的操作前非常有用。它們提供快速建立還原點的方法，必要時可以從那裡還原。

手動建立快照

快照捕捉的是你分支在某一時間點的狀態。你可以手動在根分支建立快照。每個專案手動快照限制為 10 次（參見專案限制）。你可以從專案中的任何分支還原到這些快照。

建立快照

快照是即時建立的，且在對結構或資料做出重大變更前非常有用。

UI

請到 Lakebase App 中的專案，並在分支導覽中選擇 備份與還原 。點擊 「建立快照 」以擷取你資料的當前狀態。

具備預載範例 SQL 的 SQL 編輯器

Python SDK

create_snapshot 傳回長時間執行的作業。呼叫 .wait() 封鎖直到快照可用。結果為 Snapshot。 source_branch 是必要欄位，而到期時間也是必要的：請在 expire_time、no_expiry 或 ttl 之中，恰好設定一個。你可以選擇使用 source_branch_lsn 或 source_branch_time 釘選某個時間點。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Snapshot, SnapshotSpec, Duration

w = WorkspaceClient()

snapshot = Snapshot(
    spec=SnapshotSpec(
        source_branch="projects/my-project/branches/main",
        ttl=Duration(seconds=604800),  # 7 days
    )
)

result = w.postgres.create_snapshot(
    parent="projects/my-project",
    snapshot=snapshot,
    snapshot_id="my-snapshot",
).wait()

print(f"Snapshot created: {result.name}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;
import com.google.protobuf.Duration;

WorkspaceClient w = new WorkspaceClient();

SnapshotSpec spec = new SnapshotSpec()
    .setSourceBranch("projects/my-project/branches/main")
    .setTtl(Duration.newBuilder().setSeconds(604800L).build());  // 7 days

Snapshot snapshot = new Snapshot().setSpec(spec);

Snapshot result = w.postgres().createSnapshot(
    new CreateSnapshotRequest()
        .setParent("projects/my-project")
        .setSnapshot(snapshot)
        .setSnapshotId("my-snapshot")
).waitForCompletion();

System.out.println("Snapshot created: " + result.getName());

CLI

snapshot_id 是位於 project 之後的位置引數。規格對應到 --json 車身：

databricks postgres create-snapshot projects/my-project my-snapshot \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/main",
      "ttl": "604800s"
    }
  }'

curl

建立快照是一項長時間的操作。此要求會傳回一項作業，您可持續輪詢，直到作業完成。已完成的作業會解壓縮至 Snapshot 資源。在實務中，快照很快就會變成 AVAILABLE。

快照規範需要 source_branch. 請將時間點與到期日設定如下：

時間點（選用）：請設定 source_branch_lsn 或 source_branch_time 其中之一（兩者互斥）。省略兩者，以便快照目前分支的負責人。
到期時間（必填）：請僅設定 expire_time（必須是未來時間的 RFC 3339 時間戳記）、ttl（以秒為單位的持續時間，例如 "604800s"）或 no_expiry: true 其中之一。

snapshot_id 為必填項目，需由你選擇，且建立後無法更改。

傳送建立請求。該 snapshot_id 置於查詢字串中，spec 映射到請求主體：

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/snapshots?snapshot_id=my-snapshot" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "source_branch": "projects/my-project/branches/main",
      "source_branch_lsn": "16/B374D848",
      "ttl": "604800s"
    }
  }'

這個回應是一個長期運作的過程：

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

輪詢運算直到 done 為 true：

curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

完成後，此操作的 response 會解壓縮為 Snapshot：

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Snapshot",
    "name": "projects/my-project/snapshots/my-snapshot",
    "status": {
      "full_size_bytes": "10485760",
      "diff_size_bytes": "524288"
    }
  }
}

大小欄位是 int64 以字串序列化的值。

直接取得快照以確認其可用性。

欲了解更多關於長期運作的資訊，請參見「長期運作」。

建立備用排程

排程自動快照，定時執行（每日、每週或每月），確保備份穩定且無需人工介入。備份排程是依分支設定，且僅適用於根分支。手動快照的限制（參見專案限制）不適用於排程快照。

每個根分支都有一個備份排程，裡面包含一個節奏列表。你閱讀時間表，並重新調整節奏。沒有獨立的建立或刪除操作，且設定空清單會關閉自動快照。你可以在 Lakebase 應用程式中設定排程，或用 Python SDK、Java SDK、Databricks CLI、Terraform、Databricks Asset Bundles 或 curl 的備份排程 API 程式化設定。

Note

程式化存取備份排程的權限目前為 Beta 階段，所有 Lakebase 工作區皆可使用。

UI

要建立或修改備份排程：

在專案的 備份與還原 頁面，點擊 編輯排程 以開啟備份排程設定對話框。
請從以下選項中選擇排班頻率：
- 無排程 – 預設關閉自動快照
- 每日 – 每天在指定時間建立快照
- 每週 – 在每週的特定一天建立快照
- 每月 – 在特定月份建立快照
根據你選擇的頻率配置排程細節。指定你想多久建立快照，以及保存多久。

設定完成後，排程所建立的快照會出現在 備份與還原 頁面，並附上標籤表示它們是自動建立的。

Python SDK

使用 get_snapshot_schedule 讀取排程，並使用 update_snapshot_schedule 設定其頻率。 update_snapshot_schedule 會以排程的資源名稱作為 name 參數，並替換整組節奏。要設定每週頻率，讓每個快照持續7天，請執行以下操作：

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import (
    SnapshotSchedule,
    ScheduleCadence,
    WeeklySchedule,
    DayOfWeek,
    Duration,
    FieldMask,
)

w = WorkspaceClient()

schedule = SnapshotSchedule(
    name="projects/my-project/branches/main/snapshot-schedule",
    schedule=[
        ScheduleCadence(
            weekly_schedule=WeeklySchedule(day_of_week=DayOfWeek.MONDAY, hour=3),
            retention=Duration(seconds=604800),  # 7 days
        )
    ],
)

w.postgres.update_snapshot_schedule(
    name="projects/my-project/branches/main/snapshot-schedule",
    snapshot_schedule=schedule,
    update_mask=FieldMask(field_mask=["schedule"]),
)

print("Schedule updated.")

要閱讀當前時程，請執行以下操作：

schedule = w.postgres.get_snapshot_schedule(
    name="projects/my-project/branches/main/snapshot-schedule"
)

for cadence in schedule.schedule:
    print(cadence)

Java 開發套件

要設定每週頻率，讓每個快照持續7天，請執行以下操作：

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;
import com.google.protobuf.Duration;
import java.util.List;

WorkspaceClient w = new WorkspaceClient();

ScheduleCadence cadence = new ScheduleCadence()
    .setWeeklySchedule(new WeeklySchedule().setDayOfWeek(DayOfWeek.MONDAY).setHour(3))
    .setRetention(Duration.newBuilder().setSeconds(604800L).build());  // 7 days

SnapshotSchedule schedule = new SnapshotSchedule()
    .setName("projects/my-project/branches/main/snapshot-schedule")
    .setSchedule(List.of(cadence));

SnapshotSchedule result = w.postgres().updateSnapshotSchedule(
    new UpdateSnapshotScheduleRequest()
        .setName("projects/my-project/branches/main/snapshot-schedule")
        .setSnapshotSchedule(schedule)
        .setUpdateMask("schedule")
).waitForCompletion();

System.out.println("Schedule updated: " + result.getName());

CLI

需要 Databricks CLI 1.16.0 及以上版本。用 get-snapshot-schedule 讀取排程，並用 update-snapshot-schedule 進行設定。第二個參數是更新遮罩，必須是 schedule。設定排程會取代整組排程頻率，且這是一項長時間執行的作業，因此該命令會等待作業完成，除非您傳入 --no-wait。

要閱讀當前時程，請執行以下操作：

databricks postgres get-snapshot-schedule \
  projects/my-project/branches/main/snapshot-schedule

要設定每週頻率，讓每個快照持續7天，請執行以下操作：

databricks postgres update-snapshot-schedule \
  projects/my-project/branches/main/snapshot-schedule \
  schedule \
  --json '{
    "schedule": [
      { "weekly_schedule": { "day_of_week": "MONDAY", "hour": 3 }, "retention": "604800s" }
    ]
  }'

要停用自動快照，請設定空排程：

databricks postgres update-snapshot-schedule \
  projects/my-project/branches/main/snapshot-schedule \
  schedule \
  --json '{ "schedule": [] }'

Terraform

使用 databricks_postgres_snapshot_schedule 資源管理排程。設定 parent 為分支資源名稱;排程本身 name 的資源名稱即由此衍生。 schedule 屬性是一份 cadence 清單，套用該資源後會取代該分支的 cadence 設定：

resource "databricks_postgres_snapshot_schedule" "this" {
  parent = "projects/my-project/branches/main"

  schedule = [{
    weekly_schedule = {
      day_of_week = "MONDAY"
      hour        = 3
    }
    retention = "604800s" # 7 days
  }]
}

Databricks 資產套件組合

在你的套件組合設定中，於 postgres_snapshot_schedules 鍵下定義排程。設定 branch 為分支資源名稱。部署該套件會取代該分支的節奏設定：

resources:
  postgres_snapshot_schedules:
    main_schedule:
      branch: projects/my-project/branches/main
      schedule:
        - weekly_schedule:
            day_of_week: MONDAY
            hour: 3
          retention: 604800s # 7 days

curl

使用 GET 讀取排程，並使用 PATCH 進行設定。更新會取代整個節奏設定，因此請一併提供所有你想保留的節奏，並傳入 update_mask=schedule。

要閱讀當前時程，請執行以下操作：

curl "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/main/snapshot-schedule" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

更新排程是一項長期的作業。要設定每週頻率，讓每個快照持續7天，請執行以下操作：

curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/main/snapshot-schedule?update_mask=schedule" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": [
      { "weekly_schedule": { "day_of_week": "MONDAY", "hour": 3 }, "retention": "604800s" }
    ]
  }'

輪詢傳回的作業，直到 done 為 true。參見長時間執行的操作。已完成的作業之 response 會解壓縮為 SnapshotSchedule。

要停用自動快照，請設定空排程：

curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/main/snapshot-schedule?update_mask=schedule" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "snapshot_schedule": { "schedule": [] } }'

週期與保留率參考資料

排程中的每個節奏恰好是以下一次重複，這些重複發生在整整一小時（UTC）時。不支援分鐘和秒。

每日：設定 hour（0–23）。
每週：設定 day_of_week （MONDAY 至 SUNDAY）及 hour （0–23）。
每月：設定 day （1–31，短月份的最後一天）及 hour （0–23）。

每個頻率也會設定 retention 持續時間，之後其快照就會過期：

保留期限必須至少1小時，最多35天。
保留原則會在建立快照時套用，且不具追溯效力。現有快照會保留原有的到期時間。只有變更後拍攝的快照才會使用新的保留。
如果同一視窗內有多個週期到期，Lakebase 會建立一個快照，並依符合條件的週期中最長的保留期限加以保留。

閱讀和更新排程都需要專案 CAN_USE 的許可。

快照保留

快照在其保留期限屆滿後會自動刪除。你可以隨時透過編輯排程來調整保留設定。請記住：

較短的保留期有助於管理保留預定快照的數量。
刪除的快照無法被恢復
手動快照不會受到備份排程保留設定的影響

取得並列出快照

你可以在 Lakebase App 的 備份與還原 頁面查看快照，或透過 API 程式化取得快照。

列出快照

UI

在 Lakebase App 的 備份與還原 頁面，你的快照會依日期列出，顯示每個快照的日期和大小。排程快照會出現在同一列表中，並附上標籤表示它們是自動建立的。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for snapshot in w.postgres.list_snapshots(parent="projects/my-project"):
    print(f"Snapshot: {snapshot.name}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.Snapshot;

WorkspaceClient w = new WorkspaceClient();

for (Snapshot snapshot : w.postgres().listSnapshots("projects/my-project")) {
    System.out.println("Snapshot: " + snapshot.getName());
}

CLI

databricks postgres list-snapshots projects/my-project --output json | jq

curl

列出專案中的快照。使用 page_size 並 page_token 瀏覽結果。空白 next_page_token 表示最後一頁：

curl "$WORKSPACE/api/2.0/postgres/projects/my-project/snapshots?page_size=20" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

{
  "snapshots": [{ "name": "projects/my-project/snapshots/my-snapshot" }],
  "next_page_token": ""
}

擷取單一快照

透過 ID 取得一個快照的詳細資訊。與建立與刪除不同，get 直接回傳 Snapshot 資源（這不是一個長時間執行的操作）。讀取時，到期時間會顯示為 expire_time 或 no_expiry。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

snapshot = w.postgres.get_snapshot(name="projects/my-project/snapshots/my-snapshot")

print(f"Snapshot: {snapshot.name}")
print(f"Source branch: {snapshot.status.source_branch}")
print(f"Full size: {snapshot.status.full_size_bytes} bytes")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.Snapshot;

WorkspaceClient w = new WorkspaceClient();

Snapshot snapshot = w.postgres().getSnapshot("projects/my-project/snapshots/my-snapshot");

System.out.println("Snapshot: " + snapshot.getName());
System.out.println("Full size: " + snapshot.getStatus().getFullSizeBytes() + " bytes");

CLI

databricks postgres get-snapshot projects/my-project/snapshots/my-snapshot --output json | jq

curl

curl "$WORKSPACE/api/2.0/postgres/projects/my-project/snapshots/my-snapshot" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

從快照還原

若要使用快照，請先從該快照建立新分支，將其還原。沒有原地還原：你目前的分支保持不變，並用快照資料建立 新的根分支 。

UI

在 Lakebase App 的 備份與還原 頁面上，快照會依日期列出。找到你想還原的快照，然後點選還原。會出現確認對話方塊，說明接下來會發生什麼：還原會立即完成，你目前的分支保持不變，並且會建立一個新分支，名稱類似 branch_from_snapshot_ 的格式，後面附加快照的日期和時間。確認你想執行這個操作，請點擊還原。會用快照資料建立 新的根分支 。你目前的分支保持不變。

還原完成後，你會看到成功訊息以及新分支 的總覽 頁面。標題為「 連接新分支以預覽還原資料 」的章節說明，你可以從應用程式或用戶端連線來驗證還原資料。

從快照還原後的分支概覽

點擊 「取得連線詳情 」即可開啟對話框，內含新分支的連線資訊：分支、計算、資料庫、角色，以及可複製的連接字串。分支的計算在啟動時可能會顯示為「待處理」。一旦啟動，你就可以用連接字串來連接。

你新分行還可以做的其他事情：

預覽資料。 在更改應用程式設定前，請使用新分支的連線細節檢查資料並確認還原。請參閱「連接至您的資料庫」。
重新命名分支。 從分支概覽或分支列表中給分支一個更明確的名稱。請參閱更新分支設定。
設為預設。 如果你對還原的資料感到滿意，可以將此分支設為專案的預設分支。請參見預設設定。
請將你的申請指向新分行。 確定資料正確後，更新應用程式的連線設定，使用該分支的連線細節。
移除或保留之前的分支。 如果你不再需要，可以刪除之前使用的分支，或者保留它作為備份。參見刪除分支。

你可以從專案的分支頁面管理新分支和所有專案分支，該頁面還原後的分支會與其他分支並列顯示為根分支。

Python SDK

沒有獨立的還原操作。建立分支，並將 source_snapshot 設為快照的資源名稱。這會讓分支建立經由還原路徑進行，並產生一個含有該快照資料的新根分支。 source_snapshot 與 source_branch_lsn、source_branch_time 和 source_branch 互斥，且該分支仍需設定到期條件（no_expiry、ttl 或 expire_time）。將 source_snapshot 與 replace_existing: true 一併設定，會對現有的目標分支執行更新插入，這是一種冪等還原。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

branch = Branch(
    spec=BranchSpec(
        source_snapshot="projects/my-project/snapshots/my-snapshot",
        no_expiry=True,
    )
)

result = w.postgres.create_branch(
    parent="projects/my-project",
    branch=branch,
    branch_id="restored-branch",
).wait()

print(f"Branch created: {result.name}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

BranchSpec spec = new BranchSpec()
    .setSourceSnapshot("projects/my-project/snapshots/my-snapshot")
    .setNoExpiry(true);

Branch branch = new Branch().setSpec(spec);

Branch result = w.postgres().createBranch(
    new CreateBranchRequest()
        .setParent("projects/my-project")
        .setBranch(branch)
        .setBranchId("restored-branch")
).waitForCompletion();

System.out.println("Branch created: " + result.getName());

CLI

databricks postgres create-branch projects/my-project restored-branch \
  --json '{
    "spec": {
      "source_snapshot": "projects/my-project/snapshots/my-snapshot",
      "no_expiry": true
    }
  }'

Terraform

若要從快照還原，請宣告 databricks_postgres_branch，並在其 spec 中設定 source_snapshot。 Terraform 對快照的支援僅限於此還原路徑——沒有 Terraform 資源可用於建立、列出或刪除快照。

resource "databricks_postgres_branch" "restored" {
  branch_id = "restored-branch"
  parent    = "projects/my-project"
  spec = {
    source_snapshot = "projects/my-project/snapshots/my-snapshot"
    no_expiry       = true
  }
}

curl

沒有獨立的還原操作。要還原快照，請建立一個新分支，並在分支規範中設定 source_snapshot 快照的資源名稱。此方法會將分支建立導向還原路徑，產生包含快照資料的新根分支。你現有的分支保持不變。

source_snapshot 與 source_branch、 source_branch_lsn、 source_branch_time互斥。將 source_snapshot 與 replace_existing: true 一併設定，會對現有的目標分支執行更新插入，這是一種冪等還原。所參考的快照必須是 AVAILABLE，且與新分支屬於同一個專案。

從快照建立分支。 branch_id 會放在查詢字串中：

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=restored-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "source_snapshot": "projects/my-project/snapshots/my-snapshot",
      "no_expiry": true
    }
  }'

輪詢傳回的作業，直到 done 為 true。完成的操作會解包為新的 Branch。
先連接到新分支以確認還原的資料，再將應用程式指向該分支。請參閱建立分支並連接您的資料庫。

刪除快照

刪除的快照無法被恢復。

UI

在 Lakebase 應用程式的 備份與還原 頁面，找到快照，打開烤肉選單圖示。烤肉串選單，選擇 刪除快照。

Python SDK

刪除快照是一個長期操作。呼叫 .wait() 以阻塞直到其完成。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.postgres.delete_snapshot(name="projects/my-project/snapshots/my-snapshot").wait()

print("Snapshot deleted")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteSnapshot("projects/my-project/snapshots/my-snapshot")
    .waitForCompletion();

System.out.println("Snapshot deleted");

CLI

databricks postgres delete-snapshot projects/my-project/snapshots/my-snapshot

curl

刪除快照是一個長期操作。請求會回傳一個操作。已完成作業的回應為空白。

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project/snapshots/my-snapshot" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

輪詢傳回的作業，直到 done 為 true。

快照儲存成本

自 2026 年 6 月 1 日起，Lakebase 的快照儲存需計費。

計費依快照類型而定：

手動快照會按完整快照收費。
排程快照在排程中的第一個快照時以完整快照收費，之後排程快照則以增量（delta）儲存方式收費。

每個快照的大小會顯示在 備份與還原 頁面。價格詳情請參閱 Lakebase 價格頁面。

Limitations

快照 API 有以下限制：

快照是不可變更的。 沒有更新操作。來源分支、時間點選擇器和到期日都是建立時固定的，無法更改。
沒有原地還原。 你只能透過從快照建立新分支來還原該快照。
同一個專案，快照可用。 來源快照必須在該 AVAILABLE 狀態內，且必須屬於與新分支相同的專案。
還原欄位彼此互斥。 在建立分支請求中， source_snapshot 不能與 source_branch分支 LSN 或分支時間戳合併。它可以與 replace_existing 現有目標分支的上繼結合。
Terraform。 提供者僅支援透過 databricks_postgres_branch 上的 source_snapshot 參數從快照還原。 Terraform 沒有資源可以建立、列出或刪除快照。
測試版可用性。 快照 API 目前處於測試階段，並對所有 Lakebase 工作區開放。

分支 — Lakebase 分支的運作方式
Lakebase API 指南 — 認證、資源命名與長期執行操作

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-30

Snapshots

何時使用快照

手動建立快照

建立快照

UI

Python SDK

Java 開發套件

CLI

curl

建立備用排程

UI

Python SDK

Java 開發套件

CLI

Terraform

Databricks 資產套件組合

curl

週期與保留率參考資料

快照保留

取得並列出快照

列出快照

UI

Python SDK

Java 開發套件

CLI

curl

擷取單一快照

Python SDK

Java 開發套件

CLI

curl

從快照還原

UI

Python SDK

Java 開發套件

CLI

Terraform

curl

刪除快照

UI

Python SDK

Java 開發套件

CLI

curl

快照儲存成本

Limitations

Related

意見反應

其他資源