在 Unity 目錄中註冊 Lakebase 資料庫

在 Unity Catalog 註冊 Lakebase 資料庫後，會建立一個只讀目錄，代表你的 Postgres 資料庫，實現湖屋與交易工作負載間的統一資料治理與跨來源分析。

為什麼要在 Unity 目錄註冊

註冊有多項好處：

統一治理：將 Unity Catalog 的治理控制——權限、血統追蹤及審計日誌——與 Lakehouse 資料同時應用於 Lakebase 資料。

跨來源查詢：從單一 SQL 介面查詢 Unity 目錄資料表與 Lakebase 資料庫，實現結合交易與分析資料的分析。

集中式發現：透過目錄總管，在工作空間中與其他資料來源一起尋找並發掘 Lakebase 的資料庫、結構與資料表。

整合工作流程：在 Azure Databricks 儀表板與應用程式中使用 Lakebase 資料，無需切換上下文或管理獨立連線。

運作方式

註冊會建立一個唯讀的 Unity 目錄目錄，鏡像你的 Postgres 資料庫結構，透過 Unity 目錄的治理層提供對資料庫物件（結構、資料表、檢視）的元資料存取。

你從目錄檔案總管發起註冊，而非從 Lakebase 介面啟動，後者自然整合於 Unity 目錄的目錄建立工作流程。

報名後：

• 您的 Lakebase 資料庫會以 Unity 目錄的形式出現
• Unity 目錄的權限控制誰可以查看和查詢資料庫
• 目錄仍為唯讀狀態——您需透過 Lakebase 管理實際的資料庫

先決條件

• 一個已有至少一個資料庫的 Lakebase 專案
• CREATE CATALOG Unity Catalog Metastore 的權限
• 一個無 伺服器 的 SQL 倉庫，用來查詢已註冊的目錄。 Pro 與 Classic SQL 倉庫不被支援，並會回傳權限錯誤。

註冊資料庫

UI

1. 用應用程式切換器切換到 分析和人工智慧。
2. 在目錄檔案總管中，點擊加號按鈕並 建立目錄。
3. 輸入目錄名稱（例如）。 lakebase_catalog
4. 選擇 Lakebase Postgres 作為目錄類型，然後選擇 自動縮放 選項。
5. 選擇你的專案、分支和 Postgres 資料庫。
6. 點擊 建立。

目錄會出現在目錄總管中，您可以找到結構、資料表和檢視，並使用 SQL 倉庫查詢。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Catalog, CatalogCatalogSpec

w = WorkspaceClient()

catalog = w.postgres.create_catalog(
    catalog=Catalog(spec=CatalogCatalogSpec(
        postgres_database="mydb",
        branch="projects/my-project/branches/production",
    )),
    catalog_id="my-catalog",
).wait()

print(f"Catalog registered: {catalog.name}")

Java 開發套件

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

WorkspaceClient w = new WorkspaceClient();

Catalog catalog = w.postgres().createCatalog(
    new CreateCatalogRequest()
        .setCatalogId("my-catalog")
        .setCatalog(new Catalog()
            .setSpec(new CatalogCatalogSpec()
                .setPostgresDatabase("mydb")
                .setBranch("projects/my-project/branches/production"))))
    .waitForCompletion();

System.out.println("Catalog registered: " + catalog.getName());

curl (Unix指令)

curl -X POST "https://your-workspace.cloud.databricks.com/api/2.0/postgres/catalogs?catalog_id=my-catalog" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_database": "mydb",
      "branch": "projects/my-project/branches/production"
    }
  }'

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

探索已註冊資料庫

註冊後，進入目錄總管中的目錄，尋找結構、資料表和檢視。 點擊任一表格可查看結構細節、樣本資料及血統資訊。

Unity Catalog 會自動同步 Lakebase 資料庫中的元資料。 當你在 Lakebase 新增或修改資料表時，請刷新目錄檢視以查看更新。

檢查註冊狀態

要以程式方式取得目錄的當前註冊資訊：

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

catalog = w.postgres.get_catalog("catalogs/my-catalog")
print(f"Database: {catalog.status.postgres_database}")
print(f"Branch: {catalog.status.branch}")

Java 開發套件

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

WorkspaceClient w = new WorkspaceClient();

Catalog catalog = w.postgres().getCatalog("catalogs/my-catalog");
System.out.println("Database: " + catalog.getStatus().getPostgresDatabase());
System.out.println("Branch: " + catalog.getStatus().getBranch());

curl (Unix指令)

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

查詢註冊資料庫

使用 SQL 倉庫或任何連接 Unity 目錄的工具查詢已註冊的 Lakebase 資料庫：

-- Query a registered Lakebase database
SELECT * FROM chatbot_catalog.public.conversations
WHERE created_at >= current_date - INTERVAL 7 DAYS;

-- Join Lakebase and lakehouse data
SELECT
  c.conversation_id,
  c.user_id,
  c.agent_response,
  u.user_name,
  u.subscription_tier
FROM chatbot_catalog.public.conversations c
JOIN main.user_analytics.users u
  ON c.user_id = u.user_id;

唯讀目錄確保查詢不會透過 Unity Catalog 修改你的 Lakebase 資料庫。 若要修改資料，請使用 Lakebase SQL 編輯器或直接連接您的資料庫。

權限和存取控制

Unity 目錄權限控制對已註冊 Lakebase 資料庫的存取：

• 目錄所有權：註冊資料庫的使用者即成為目錄擁有者
• 讀取存取：授權 USE CATALOG 及 SELECT 權限，允許他人查詢資料庫
• Metastore 管理員：Metastore 管理員可管理所有註冊目錄

要授權存取已註冊資料庫：

-- Grant read access to a group
GRANT USE CATALOG ON CATALOG chatbot_catalog TO `ai-engineering`;
GRANT SELECT ON CATALOG chatbot_catalog TO `ai-engineering`;

Unity Catalog 中所設定的權限可用來透過 SQL 倉庫控制查詢存取。 直接連接到你的 Lakebase 資料庫時，會獨立地使用 Postgres 的角色與權限。

取消註冊資料庫

取消註冊會將該目錄從 Unity 目錄中移除，但不會影響你的 Lakebase 資料庫。 該資料庫仍可透過 Lakebase 及直接 Postgres 連線存取。

UI

在目錄總管中選擇目錄，點擊 ，然後選擇 刪除。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.postgres.delete_catalog("catalogs/my-catalog").wait()

Java 開發套件

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteCatalog("catalogs/my-catalog").waitForCompletion();

curl (Unix指令)

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

局限性

唯讀存取：從 Lakebase 資料庫註冊的目錄為唯讀。 你無法透過 Unity Catalog 查詢修改資料。

需要無伺服器 SQL 倉庫：你只能透過無伺服器 SQL 倉庫查詢已註冊的 Lakebase 目錄。 Pro 和 Classic SQL Warehouse 不支援此功能。

每個目錄單一資料庫：每個 Unity 目錄代表一個 Lakebase 資料庫。 要公開多個資料庫，請分別註冊每一個資料庫。

元資料同步：Unity 目錄會快取元資料以減少 Postgres 請求。 新物件可能不會立即出現。 點擊 」即可觸發完整刷新。

不支援分支資料庫註冊：你無法將分支資料庫註冊為獨立的 Unity 目錄。 當你從已註冊在 Unity Catalog 的資料庫建立分支時，該分支會繼承父目錄的註冊元資料。 這會導致新的目錄註冊失敗。

其他資源

• 管理資料庫
• 了解分支
• 使用 SQL 編輯器查詢