用同步的資料表來提供湖屋資料

同步資料表讓你可以透過 Lakebase Postgres 提供 lakehouse 資料。 Unity 目錄資料表會同步到 Postgres，讓應用程式能以低延遲直接查詢湖屋資料。 此過程通常稱為反向ETL。 Lakehouse 優化於分析與豐富化，而 Lakebase 則設計用於需要快速查詢式查詢及交易一致性的營運工作負載。

什麼是同步表格？

同步資料表讓你能透過 Lakebase Postgres 提供來自 Unity 目錄的分析級資料，讓需要低延遲查詢與完整 ACID 交易的應用程式也能使用。 它們彌合了分析儲存與營運系統之間的鴻溝，確保資料隨時可用於即時應用程式。

支援來源

同步資料表支援以下 Unity 目錄原始碼類型：

• 管理型與外部 Delta 表
• 管理的與外部的 Iceberg 資料表
• 觀點與具體化觀點

運作方式

Databricks 的同步資料表 會在 Lakebase 中建立您 Unity Catalog 資料的受控副本。 當你建立同步表格時，你會得到：

1. Unity Catalog 中一個同步的表格，參考同步管線
2. Lakebase 中的 Postgres 表格 （唯讀，應用程式可查詢）

例如，你可以將黃金數據表、特徵工程或機器學習輸出從 analytics.gold.user_profiles 同步到新的同步表 analytics.gold.user_profiles_synced。 在 Postgres 中，Unity 目錄的結構名稱會變成 Postgres 架構名稱，因此會顯示為 gold.user_profiles_synced：

SELECT * FROM gold.user_profiles_synced WHERE user_id = 12345;

應用程式連接標準 Postgres 驅動程式，並查詢同步資料及自身運作狀態。

同步管線使用受管理的 Lakeflow 管線，根據來源資料表中的變更，持續更新 Unity Catalog 同步資料表和 Postgres 資料表。 每次同步最多可使用16個連線連接你的Lakebase資料庫。

Lakebase Postgres 支援最多 1,000 個並行連線，並提供交易保證，因此應用程式能在同一資料庫中讀取豐富資料，同時處理插入、更新與刪除。

與 LTAP 直接寫入的加速同步

LTAP 直接寫入是 LTAP 架構 的一項功能，可加快大量資料載入。 預設是關閉的，你可以在「建立同步資料表」對話框的同步設定中選擇 LTAP 直接寫入，依照同步資料表來選擇。 啟用後，它會直接將資料寫入支援 Lakebase 分支的儲存層，而不是透過即時運算端點進行大量寫入，這樣載入完成速度會更快，且執行時不會增加查詢負擔。

LTAP 直接寫入加速的部分取決於同步模式：

• 所有模式：初始載入。 每個同步資料表都會先載入完整原始碼，而第一個載入會使用 LTAP 直接寫入。
• 快照：每一次後續同步都會執行完整重新整理，因為 快照 模式每次都會進行完整重新整理。
• 觸發 與 連續：僅限初始載入。 後續更新是透過變更資料流逐步應用，而非批量載入。

同步模式

根據您的應用程式需求選擇合適的同步模式：

在 「建立同步資料表 」對話框中， 快照 與 觸發 皆為 隨選 同步模式，皆可於 進階設定中取得，而 連續 則為獨立模式。

來源需求取決於同步模式：

• Snapshot 每次同步時都會複製所有資料，因此來源端只需支援 SELECT *。
• 觸發和連續會以增量方式套用資料列層級的變更，因此來源必須提供變更資料摘要。 在來源端啟用寫入時 變更資料饋送，或使用自動變更資料饋送。 如果 Triggered 或 Continuous 類型的來源沒有變更資料摘要，UI 會顯示警告，並附上要執行的確切 ALTER TABLE 指令。

自動變更資料流 會在讀取時計算列層級變更，而非在原始碼上要求寫入時變更資料。 這讓更多原始碼類型，包括 Apache Iceberg 資料表，能在 觸發 或 連續 模式下同步。 關於自動變更資料饋提供支援的來源類型，請參閱 自動變更資料饋送 文件。

範例使用案例

你可以在資料服務的情境中使用同步資料表：

• 為 Databricks 應用程式提供全新使用者設定檔的個人化引擎
• 用於提供模型預測或從湖倉計算特徵值的應用程式
• 客戶界面的儀表板，即時提供 KPI 數據
• 詐欺偵測服務，提供風險分數以立即採取行動
• 支援使用 Lakehouse 數據提供豐富客戶紀錄的工具

建立同步表格

先決條件

您需要：

• 一個啟用 Lakebase 的 Databricks 工作空間。
• 一個 Lakebase 專案（參見 建立專案）。
• 一個 Unity 目錄表格來同步。
• 建立同步資料表的權限。 你需要在任何使用的 schema 上具有 USE_SCHEMA 和 CREATE_TABLE 權限。 要授予這些權限，請參閱 在 Unity Catalog 中管理權限。

對於 觸發 模式或 連續 模式，來源必須提供變更資料串流。 你可以在符合資格的 Delta Lake 來源資料表啟用舊有變更資料饋送，或對像 Apache Iceberg 表格這類來源使用 自動變更資料饋送 。

若要在 Delta 來源資料表上啟用寫入時變更資料摘要，請執行：

ALTER TABLE your_catalog.your_schema.your_table
SET TBLPROPERTIES (delta.enableChangeDataFeed = true)

關於容量規劃與資料型態相容性，請參見 資料型別與相容 性及 容量規劃。

UI

1. 在 Lakehouse 中，前往工作區側邊欄中的 Catalog，然後選取您要同步的 Unity Catalog 資料表。

   

2. 從表格詳細檢視點選「 建立>同步資料表 」。

   

3. 在 「建立同步資料表 」對話框中，設定以下區塊，然後點擊 「建立」：

   Destination

   • 名稱：選擇同步資料表的目錄與結構，然後輸入資料表名稱。 這樣可以建立一個 Unity Catalog 同步的表格和一個可以查詢的 Postgres 表格。 目錄和結構清單只包含 Unity 目錄中擁有 USE_SCHEMA 和 CREATE_TABLE 權限的結構。 如果你沒看到預期的結構，請向你的目錄管理員確認你的權限。
   • Lakebase Postgres 資料庫：將資料庫類型設為自動縮放，然後選擇您的 Project、分支及 Postgres 資料庫。

   同步設定

   • 同步模式：選擇 依需求 或 連續。 隨 選視訊時，請展開 進階設定 ，選擇 快照 或 觸發。 請參見 同步模式 以獲得指引。
   • LTAP 直接寫入：（選用）選擇此勾選框以加速初始負載。 此選項支援運行 Postgres 16、17 或 18 的 Lakebase 專案。 請參見 LTAP 直接寫入的加速同步。

   管線設定

   • 管線：選擇「建立新」以建立同步資料表的管線，或使用現有資料表重用一個。
   • 無伺服器使用政策：（可選）為同步管線選擇無伺服器使用政策。

   架構

   • 主金鑰：驗證主金鑰（通常為自動偵測）。 若每個主要鍵值在來源中都是唯一的，則選擇保持 唯一 。 若主鍵值可重複，則清除 唯一 並設定 時間序列鍵。

     這很重要

     主鍵中的資料行在同步處理的資料表中不可為空。 主鍵欄中有空值的列會被 排除在同步之外。

   • 時間序列鍵：（可選）當主要鍵值在來源中重複時，選擇欄位來設定重複資料刪除。 同步後的表格僅包含每個主鍵具有最新時間序列鍵值的列。 關於沒有時間序列鍵的失敗模式，請參見 重複鍵。

   • 自訂欄位類型：（選用）覆寫來源欄位對應至 Postgres 資料類型的方式。 參見 自訂類型映射。

   如果你選擇了 觸發 或 持續 ，且還沒啟用變更資料串流，你會看到警告，裡面有執行的精確指令。 關於資料型態相容性的問題，請參見 資料型別與相容性。

4. 監控 目錄中同步的表格。 Overview 標籤會顯示同步狀態、設定、管線狀態以及最後一次同步時間戳記。 使用 同步 立即手動刷新。

CLI

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true
    }
  }'

SYNCED_TABLE_ID位置論證使用格式 catalog.schema.table。 在 Postgres 中，表格 {table} 是在架構 {schema} 中建立，位於你設定的資料庫 postgres_database（這裡，指 mydb）。 指令預設會等待操作完成。 關於所有可用選項，請參見 databricks postgres create-synced-table。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import (
    SyncedTable,
    SyncedTableSyncedTableSpec,
    SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy,
)

w = WorkspaceClient()

synced_table = w.postgres.create_synced_table(
    synced_table=SyncedTable(spec=SyncedTableSyncedTableSpec(
        source_table_full_name="main.sales.orders",
        branch="projects/my-project/branches/production",
        primary_key_columns=["order_id"],
        scheduling_policy=SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy.SNAPSHOT,
        postgres_database="mydb",
        create_database_objects_if_missing=True,
    )),
    synced_table_id="my-catalog.sales.orders",
).wait()

print(f"Synced table created: {synced_table.name}")

synced_table_id 使用格式 catalog.schema.table 並成為 Unity Catalog 同步的資料表名稱。 在 Postgres 中，表格 {table} 是在架構 {schema} 中建立，位於你設定的資料庫 postgres_database（這裡，指 mydb）。

Java 開發套件

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

WorkspaceClient w = new WorkspaceClient();

SyncedTable syncedTable = w.postgres().createSyncedTable(
    new CreateSyncedTableRequest()
        .setSyncedTableId("my-catalog.sales.orders")
        .setSyncedTable(new SyncedTable()
            .setSpec(new SyncedTableSyncedTableSpec()
                .setSourceTableFullName("main.sales.orders")
                .setBranch("projects/my-project/branches/production")
                .setPrimaryKeyColumns(List.of("order_id"))
                .setSchedulingPolicy(SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy.SNAPSHOT)
                .setPostgresDatabase("mydb")
                .setCreateDatabaseObjectsIfMissing(true))))
    .waitForCompletion();

System.out.println("Synced table created: " + syncedTable.getName());

curl (Unix指令)

curl -X POST "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables?synced_table_id=my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true
    }
  }'

這會返回一個長時間執行的操作。 對返回 name 的欄位進行輪詢直到 done: true。 參見 長時間執行的操作。 關於認證設定，請參見認證。

排程或觸發後續同步

初始快照會在建立時自動執行。 對於 快照 和 觸發 模式，後續的同步需要手動啟動。 連續 模式是自我管理。

資料庫資料表同步流程任務

Lakeflow Jobs 中的 資料庫資料表同步管線 任務會以同步資料表的管線作為工作流程步驟執行。 用表格更新觸發器或排程來設定工作。

觸發源資料表更動

當來源 Unity 目錄資料表更新時，該工作會被觸發。 觸發模式中，只有新增的變更會逐步套用，帶來近乎即時的新鮮感，且不會像連續模式那樣需要持續的成本。

1. 在您的工作區中，點擊側邊欄中的工作與流程。
2. 點擊 建立職缺 或開啟現有職缺。
3. 在 任務 標籤中，點擊 + 新增其他任務類型。
4. 在 「擷取與轉換」中，選擇 資料庫資料表同步管線。
5. 在 管線 欄位中，選擇與你同步資料表相關的管線。
6. 在 排程與觸發器中，點選 新增觸發器。
7. 選擇「 資料表更新 」作為觸發類型。
8. 在 資料表中，選擇要監控的來源 Unity 目錄資料表。
9. 點選 [儲存]。

根據排程觸發

同步器以固定的節奏運行。 非常適合 快照 模式，因為通常每晚或每週完整刷新是最有效率的模式。

1. 請依照上述步驟 1–5 將資料庫 資料表同步管線 任務加入工作。
2. 在 排程與觸發器中，點選 新增觸發器。
3. 選擇「排程」作為觸發類型。
4. 設定你的 cron 排程和時區，然後點 選儲存。

檢查同步狀態

要檢查同步資料表的當前狀態和最後一次同步時間：

UI

在 目錄中，導覽到你已同步的資料表，並選擇 「概覽 」標籤。它顯示目前的同步狀態、流水線狀態和最後一次同步時間戳記。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

table = w.postgres.get_synced_table("synced_tables/my-catalog.sales.orders")
print(f"State: {table.status.detailed_state}")
print(f"Last sync: {table.status.last_sync_time}")
print(f"Message: {table.status.message}")

Java 開發套件

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

WorkspaceClient w = new WorkspaceClient();

SyncedTable table = w.postgres().getSyncedTable("synced_tables/my-catalog.sales.orders");
System.out.println("State: " + table.getStatus().getDetailedState());
System.out.println("Last sync: " + table.getStatus().getLastSyncTime());
System.out.println("Message: " + table.getStatus().getMessage());

curl (Unix指令)

curl "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables/my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

資料型態與相容性

Unity Catalog 的資料型別在建立同步資料表時會映射到 Postgres 型別。 複雜型態（ARRAY、MAP、struct）會在 Postgres 中以 JSONB 形式儲存。

自訂型態映射

當你建立同步表格時，可以用 來覆蓋特定欄位預設的 Delta-to-Postgres 類型映射。type_overrides

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

自訂型別映射可以透過 API、CLI 和 Databricks SDK 在建立同步資料表時設定。

對於來源資料表 main.docs.chunks(id BIGINT, title STRING, embedding ARRAY<FLOAT>)，以下會在 Postgres 中將 title 對應到 embedding，並將 varchar(256) 對應到 vector(1024)：

databricks postgres create-synced-table main.docs.chunks_pg \
  --json '{
    "spec": {
      "source_table_full_name": "main.docs.chunks",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true,
      "type_overrides": [
        { "column_name": "title", "pg_type": "PG_SPECIFIC_TYPE_VARCHAR", "size": 256 },
        { "column_name": "embedding", "pg_type": "PG_SPECIFIC_TYPE_VECTOR", "size": 1024 }
      ]
    }
  }'

如果沒有覆寫，title 會是 TEXT，而 embedding 會是 JSONB。

處理無效字元

某些字元如空位元組（0x00）在 Unity Catalog 的字串、陣列、地圖或結構體欄位中被允許，但在 Postgres 的 TEXT 或 JSONB 欄位中則不支援。 這可能導致同步失敗，出現如下錯誤：

ERROR: invalid byte sequence for encoding "UTF8": 0x00
ERROR: unsupported Unicode escape sequence DETAIL: \u0000 cannot be converted to text

• 當最上層字串數據行中出現 Null 位元組時，就會發生第一個錯誤，該資料行會直接對應至 Postgres TEXT。
• 第二個錯誤發生在一個空位元組出現在嵌套於複雜型別（STRUCT、、 ARRAY或 MAP）內的字串中，該字串序列化為 JSONB。 在串行化期間，所有字串都會轉換成 Postgres TEXT，其中 \u0000 不允許。

解決方案：

• 淨化字串欄位：同步前移除不支援的字元。 對於 STRING 欄位中的空位元組：

  SELECT REPLACE(column_name, CAST(CHAR(0) AS STRING), '') AS cleaned_column FROM your_table
  

• 轉換為 BINARY：對於需要保留原始位元組的 STRING 欄位，請轉換為 BINARY 類型。

容量規劃

在規劃同步資料表實作時，請考慮以下資源需求：

• 連線使用：每個同步資料表最多可使用 16 個連線到您的 Lakebase 資料庫，這些連線會計入專案的連線上限。
• 大小配額：所有同步資料表的邏輯資料總數計入分支 的資料庫儲存配額。 如果你需要更高的配額，請聯絡 Databricks 客服。 個別資料表沒有配額限制，但 Databricks 建議需要更新的資料表不要超過 1 TB。
• 完整刷新大小：觸發完全刷新時，Postgres 的舊版本不會被刪除，直到新同步完成。 這兩個版本在重新整理期間都會暫時列入邏輯資料庫大小配額的計算。
• 每個來源的表格：單一來源表格最多可有 20 個同步資料表。
• 命名要求：資料庫、結構與資料表名稱只能包含字母數字字元及底線（[A-Za-z0-9_]+）。
• 來源識別碼指引：避免在 Unity Catalog 資料表的欄位或資料表名稱中使用大寫字母或特殊字元。 如果你保留它們，在 Postgres 中引用時必須引用這些識別碼。
• 架構演化：僅支援加法式架構變更（如新增欄位）用於觸發模式與連續模式。
• 更改資料表定義：任何介面（UI、SDK、CLI、REST API、Terraform 或 DAB）都不支援更新同步資料表的定義。 若要更改主鍵或時間序列鍵，或進行非加法結構變更，請刪除同步資料表並建立新資料表。
• 重複鍵：如果來源資料表中的兩個資料列具有相同的主鍵，除非你使用 時間序列鍵 設定去重，否則同步管線將會失敗。
• API 冪等性：同步資料表 API 具冪等性，因此在發生暫時性錯誤時請重試，以確保作業能及時完成。
• 更新速率：Lakebase 的同步管線支援連續與觸發寫入，每個容量單元（CU）約每秒 150 行，快照寫入速度最高達每 CU 2,000 列。

Postgres 同步資料表允許的操作

Azure Databricks 建議僅在 Postgres 中對同步資料表執行以下操作，以防止意外覆寫或資料不一致：

• 唯讀查詢
• 建立索引
• 刪除資料表（在從 Unity 目錄移除同步資料表後釋放空間）

雖然 Postgres 中同步的資料表可以用其他方式修改，但這會干擾同步流程。

擁有權和許可權

同步資料表屬於內部 databricks_writer_<dbid> 角色，而非建立該資料表的使用者，因為同步管線負責管理（參見 Postgres 角色）。 僅擁有者權限的指令，例如設定列層級安全，無法直接在同步資料表上執行。

建立同步資料表的使用者可存取

當你建立同步資料表時，你的 Azure Databricks 身份會自動獲得使用該資料表的權限。 不需要 databricks_superuser 採取行動。 你的身份會在同步表中獲得以下權限：

你未獲授與 INSERT 或 UPDATE。 資料管線擁有資料表的資料，因此直接寫入的內容會在下一次重新整理時被覆寫。 DELETE 和 TRUNCATE 只會清除表格。 下一次刷新會從原始資料重新填充資料表。

這個存取權限是根據你在同步資料表上的 Unity 目錄權限來產生，並由 Unity 目錄管理。 要更改它，請更新使用者的 Unity 目錄權限。 你無法REVOKE直接從 Postgres 的 Azure Databricks 身份取得。

管理同步的數據表存取

建立同步資料表後，databricks_superuser 可以從 Postgres 讀取同步資料表。 databricks_superuser有pg_read_all_data，可讓此角色從所有資料表讀取。 它還具有 pg_write_all_data 權限，可讓此角色寫入所有表格。 這意味著 a databricks_superuser 也可以寫入 Postgres 中的同步表。 Lakebase 支援此寫入行為，如果您需要在目標資料表中進行緊急變更。 不過，Azure Databricks 建議你改為在來源資料表中進行修正。

• databricks_superuser也可以將這些許可權授與其他使用者：

  GRANT USAGE ON SCHEMA synced_table_schema TO user;
  

  GRANT SELECT ON synced_table_name TO user;
  

• databricks_superuser可以撤銷這些許可權：

  REVOKE USAGE ON SCHEMA synced_table_schema FROM user;
  

  REVOKE {SELECT | INSERT | UPDATE | DELETE} ON synced_table_name FROM user;
  

管理同步處理數據表作業

databricks_superuser可以管理哪些用戶有權在同步處理數據表上執行特定作業。 同步資料表的支援作業如下：

• CREATE INDEX
• ALTER INDEX
• DROP INDEX
• DROP TABLE

同步處理數據表會拒絕所有其他 DDL 作業。

若要將這些許可權授與其他使用者， databricks_superuser 必須先在 上 databricks_auth建立擴充功能：

CREATE EXTENSION IF NOT EXISTS databricks_auth;

然後，databricks_superuser可以新增使用者來管理同步資料表：

SELECT databricks_synced_table_add_manager('"synced_table_schema"."synced_table"'::regclass, '[user]');

databricks_superuser可以將使用者移除出同步處理資料表的管理：

SELECT databricks_synced_table_remove_manager('[table]', '[user]');

databricks_superuser可以檢視所有管理員：

SELECT * FROM databricks_synced_table_managers;

刪除同步的表格

從 Unity 目錄刪除同步的表格也會移除對應的 Postgres 表格。

UI

在 目錄中，找到你已同步的表格，點擊 選單，然後選擇 刪除。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.postgres.delete_synced_table("synced_tables/my-catalog.sales.orders").wait()

Java 開發套件

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteSyncedTable("synced_tables/my-catalog.sales.orders").waitForCompletion();

curl (Unix指令)

curl -X DELETE "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables/my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

目錄整合

• 目錄複製： 在以 Postgres 資料庫為目標的標準目錄中建立同步處理的資料表，也註冊為個別的資料庫目錄，會導致同步處理的資料表出現在標準和資料庫目錄下的 Unity 目錄中。

其他選項

關於將資料同步至非 Databricks 系統，請參見 Partner Connect 反向 ETL 解決方案 ，如 Census 或 Hightouch。

瞭解更多資訊