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

同步表格讓你能透過 Lakebase Postgres 提供來自 Unity Catalog 的分析級資料。 Unity 目錄資料表會同步到 Postgres,讓應用程式能以低延遲直接查詢湖屋資料。 此過程通常稱為反向萃取、轉換與載入(ETL)。 lakehouse 針對分析與資料增強進行最佳化,而 Lakebase 則設計用於需要快速查找式查詢及完整 ACID 交易的營運工作負載。 同步資料表透過讓資料隨時可供即時應用程式使用,彌合分析儲存與營運系統之間的落差。

架構圖顯示從 Lakehouse 到 Lakebase 再到應用程式的資料流

範例使用案例

你可以在資料服務的使用情境中使用同步資料表,例如:

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

支援來源

同步資料表支援以下 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資料庫。 連線限制取決於計算大小。 請參見 運算規格。

警告

雖然可以直接在 Postgres 修改同步資料表,但 Azure Databricks 嚴格建議只執行讀取查詢,以保護與來源的資料完整性。 關於同步資料表上支援的操作,請參見 Postgres 中同步資料表允許的操作。

與 LTAP 直接寫入的加速同步

這很重要

LTAP Direct Writes 目前仍處於 測試階段。 通常有已同步的表格可用。

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

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

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

備註

LTAP 直接寫入支援運行 Postgres 16、17 或 18 的 Lakebase 專案。 如果你沒有看到 LTAP 直接寫入的勾選框,工作區管理員必須從預覽頁面啟用 LTAP 直接寫入預覽。 當你 建立同步資料表時,會選擇 LTAP 直接寫入,因此你無法將其新增至現有的同步資料表。 若要在現有同步資料表中使用 LTAP 直接寫入,請刪除同步資料表並建立新資料表。

同步模式

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

模式 說明 使用時機 績效
Snapshot 一次性複製所有資料 來源端每個週期變更 >10% 的資料列 如果修改 >10% 的原始資料,效率會提升 10 倍
觸發 按需或定時執行的排定更新 來源列會依既定的頻率改變。 每次刷新時,插入、更新和刪除操作都會被同步。 成本與延遲平衡良好。 如果 <是5分鐘間隔跑,會很貴
連續的 即時串流,延遲僅數秒 變更必須在 Lakebase 中幾乎即時出現 延遲最低,成本最高。 最低間隔為15秒

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

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

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

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

建立同步表格

先決條件

您需要:

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

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

若要在 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 直接寫入預覽。 請參見 LTAP 直接寫入的加速同步。

    管線設定

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

    架構

    • 主金鑰:驗證主金鑰(通常為自動偵測)。 若每個主要鍵值在來源中都是唯一的,則選擇保持 唯一 。 若主鍵值可重複,則清除 唯一 並設定 時間序列鍵。 建立同步表後,你無法更改主鍵或時間序列鍵。

      這很重要

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

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

    • 自訂欄位類型:(選用)覆寫來源欄位對應至 Postgres 資料類型的方式。 如果你將欄位映射到 vector 或 halfvec,請先在目標資料庫安裝向量擴充功能。 參見 自訂類型映射。

    如果你選擇了 觸發 或 持續 ,且還沒啟用變更資料串流,你會看到警告,裡面有執行的精確指令。

  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。

若要覆寫預設欄位類型映射,請在 spec 中加入 type_overrides。 參見 自訂類型映射。

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. 在您的工作區中,點擊側邊欄中的工作流程圖示。工作與流程。
  2. 點擊 建立職缺 或開啟現有職缺。
  3. 在 任務 標籤中,點擊 + 新增其他任務類型。
  4. 在 「擷取與轉換」中,選擇 資料庫資料表同步管線。
  5. 在 管線 欄位中,選擇與你同步資料表相關的管線。
  6. 在 排程與觸發器中,點選 新增觸發器。
  7. 選擇「排程」作為觸發類型。
  8. 設定你的 cron 排程和時區,然後點 選儲存。

檢查同步狀態

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

備註

在同步過程中,管線在回報 INITIALIZING 事件的同時執行所有資料處理。 大型同步可以在整個執行期間回報 INITIALIZING。 這是預期之中的,並不代表管線就停滯不前。

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 會記錄來源資料表與同步資料表之間的資料譜系,並以同步管線作為相關聯的實體。 利用資料譜系追蹤同步資料表的資料來源,或在更改來源資料表前找出哪些同步資料表依賴某個來源資料表。

同步資料表沿襲有以下限制:

  • 血統僅限於表格層級。 欄位層級的資料譜系不會被記錄。
  • Lineage 在 Unity Catalog 同步表結束。 Lakebase 中的 Postgres 表格不會出現在系譜圖中,應用程式對 Postgres 表格執行的查詢也不會被記錄。
  • 建立同步資料表時會記錄資料沿襲。 在支援譜系功能尚未推出之前建立的同步資料表不會顯示譜系。 若要記錄舊有同步資料表的血統,請刪除後重新建立該資料表。 重建同步資料表時會執行完整的初始同步。
  • 資料譜系會依資料表名稱來對應。 如果你用同名重建同步資料表,lineage 也能顯示已刪除的同步資料表的同步管線。
  • 如果同步的表格也出現在資料庫目錄中(參見 目錄整合),血緣只會顯示在你建立該表格的目錄中的同步表格上。

UI

  1. 在你的工作區,點選 資料圖示目錄。

  2. 搜尋或瀏覽你同步的表格或其來源表格。

  3. 選擇「譜系」標籤。來源資料表會以上游資料表的形式出現。 同步管線在雙向中皆會以 同步表 管線條目的形式出現:上游因為會寫入同步表,下游則是因為同步執行會從同步表讀取。 管線條目是與資料沿襲相關聯的資產,而非額外資料表。

    同步資料表的 Lineage 分頁,顯示上游來源資料表和同步管線

  4. 欲查看互動式圖表,請點擊 查看血緣圖。 圖表顯示來源資料表透過同步管線連接到同步資料表。 取用端節點將讀取同步資料表的 Azure Databricks 資產分組,例如筆記本、工作與同步管線。 查詢 Postgres 表格的應用程式沒有顯示。

    系譜圖顯示一個連接到同步資料表的來源資料表

系統數據表

查詢 system.access.table_lineage 系統資料表。 同步資料表的血緣記錄具有 target_type(值為 PIPELINE)和 TABLE(值為 entity_type),且 entity_id 是同步管線的 ID。 資料譜系會立即出現在 Catalog Explorer 中,但新紀錄出現在系統資料表中可能需要一些時間。

要找到同步表格的來源:

SELECT DISTINCT source_table_full_name, entity_id AS pipeline_id
FROM system.access.table_lineage
WHERE target_table_full_name = 'analytics.gold.user_profiles_synced';

要找到所有依賴來源資料表的同步資料表,例如在你更改來源資料表的結構之前:

SELECT DISTINCT l.target_table_full_name, l.entity_id AS pipeline_id
FROM system.access.table_lineage l
JOIN system.information_schema.tables t
  ON l.target_table_full_name = concat_ws('.', t.table_catalog, t.table_schema, t.table_name)
WHERE l.source_table_full_name = 'analytics.gold.user_profiles'
  AND l.entity_type = 'PIPELINE'
  AND t.data_source_format = 'POSTGRESQL_FORMAT';

同步資料表的 data_source_format 是 POSTGRESQL_FORMAT,因此,該連接會將結果限制為同步資料表。 每個同步也會記錄同步管線對來源資料表的讀取,並帶有一個空的 target_table_full_name。 這個聯結排除了這些紀錄。 系統資料表也可以包含同一譜系的重複記錄,因此兩個查詢都會使用 DISTINCT。

關於資料譜系要求、權限及保留的詳細資訊,請參見 Unity 目錄中的資料譜系。 完整系統資料表架構,請參見 Lineage 系統資料表參考。

資料型態與相容性

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

來源資料行類型 Postgres 資料行類型
BIGINT BIGINT
BINARY BYTEA
BOOLEAN BOOLEAN
DATE DATE
小數(p, s) 數值
雙倍 雙精確度
FLOAT 真的
INT 整數
INTERVAL INTERVAL
斯莫林特 斯莫林特
STRING 簡訊
TIMESTAMP 具有時區的時間戳
TIMESTAMP_NTZ 無時區的時間戳記
TINYINT 斯莫林特
ARRAY<元素類型> JSONB
MAP<鍵類型,值類型> JSONB
STRUCT<fieldName:fieldType[, ...]> JSONB
VARIANT JSONB

備註

不支援 GEOGRAPHY、GEOMETRY 和 OBJECT 類型。

自訂型態映射

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

備註

vector和 halfvec 類型需要在目的資料庫中加一個向量擴充。 建立同步表格不會安裝擴充功能,所以在建立同步表格前先先安裝一個。 使用 lakebase_vector,它透過 Lakebase Search 加入人工神經網路向量搜尋,並將 pgvector 安裝為相依項目:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

若要在不使用 Lakebase Search 的情況下使用 vector 和 halfvec 類型,請使用 CREATE EXTENSION IF NOT EXISTS vector; 單獨安裝 pgvector。 該 varchar 型別不需要延伸。

來源資料行類型 Postgres 類型 Size 定義(pg_type) 使用案例範例
ARRAY<FLOAT>、ARRAY<DOUBLE> vector(n) 嵌入維度 PG_SPECIFIC_TYPE_VECTOR 將嵌入儲存為vector替代JSONB,準備與 lakebase_vector 進行相似性搜尋
ARRAY<FLOAT>、ARRAY<DOUBLE> halfvec(n) 嵌入維度 PG_SPECIFIC_TYPE_HALFVEC 半精度嵌入,儲存空間約為 vector 的一半
STRING varchar(n) 最大長度 PG_SPECIFIC_TYPE_VARCHAR 映射到長度受限的 varchar,而非預設的 TEXT

備註

size 對於本表中每一種類型都是必要的。 有效的範圍包括:

  • vector 以及 halfvec:1 到 16,000,表示嵌入維度的數量。
  • varchar: 1 到 10,485,760,最大字元長度。

自訂型別映射可以在建立同步資料表時設定。 在介面中,請在「建立同步資料表」對話框的「結構」下使用「自訂欄位類型」。 在 API、CLI 和 Databricks SDK 中,請使用 type_overrides.

對於來源資料表 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 中同步的資料表可以用其他方式修改,但這會干擾同步流程。

為同步資料表新增索引

會建立一個具有主鍵索引的同步表格。 若要新增其他索引,請在表格存在後在 Postgres 中建立索引。 例如,為了支援對 JSONB 欄位(例如從 VARIANT 來源欄位同步的欄位)進行包含查詢,建立一個 GIN 索引:

CREATE INDEX orders_payload_gin ON sales.orders USING GIN (payload);

你在同步資料表上建立的索引會跨同步持續存在。 每次滿載,包括每次 快照 同步和任何完整刷新,都會重建你的索引,因此每增加一個索引,都會增加這些同步所需的時間。 在 觸發 模式與 連續 模式中,每個索引也會減緩增量更新速度。

要建立索引,你必須是同步資料表的擁有者或創建者、 databricks_superuser或是被加入為同步資料表管理員的使用者。 請參閱 管理同步資料表操作。

建立索引時請記得以下幾點:

  • 已同步的資料表是分區資料表。 Postgres 不支援 CREATE INDEX CONCURRENTLY 分割表格,所以改用 CREATE INDEX 它。 CREATE INDEX 會封鎖對資料表的寫入,包括從同步管線進行的寫入,直到建置完成。 如果建置時間超過 20 分鐘,當同步正在等待時,同步會失敗且不會自動重試。 查詢仍可讀取資料表,除非有完整載入作業正等待切換為更新後的資料。 在大型資料表上,當沒有同步執行時建立索引。
  • 從 Postgres 用戶端執行耗時較長的索引建置。 在大型資料表上建立索引可能需要很長時間。 從客戶端執行建置,例如 psql ,而不是用SQL編輯器。

備註

若同步資料表使用 LTAP 直接寫入,則只有 B 樹索引能保留後續完整載入的支援。 其他索引類型,如 GIN,則讓這些載入使用標準同步路徑。 初始負載不會受影響。

擁有權和許可權

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

備註

這是 Postgres 一般規則的一個例外:如果你的 Azure Databricks 身分的登入在 Postgres 中是以角色存在,則你自行建立的物件會由你的 Azure Databricks 身分擁有。 管線會為你建立已同步的資料表。

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

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

物件 Privileges Purpose
已同步的表格 SELECT、DELETE、TRUNCATE 讀取或清除表格
Schema USAGE、CREATE 利用結構建立像索引這樣的物件

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

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

備註

這個存取權限與建立同步資料表的身份綁定。 變更管線的 Run as 身分不會重新指派該管線。 若要使用不同的擁有者身分,請在該身分下重新建立同步資料表。

管理同步的數據表存取

建立同步資料表後,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}"

目錄整合

同步的資料表可以在 Unity Catalog 中出現在多個目錄中。 當你在標準目錄中建立同步資料表,且其目的地 Postgres 資料庫也註冊為資料庫目錄時,這種目錄重複是預期的。 在這種情況下,同步的表格會同時出現在兩個型錄下。

同步到 Azure Databricks 外部的系統

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

其他資源