在 Snowflake 上執行同盟查詢

發行項
03/05/2025

本文說明如何設定 Lakehouse 同盟，在 Azure Databricks 未管理的 Snowflake 數據上執行同盟查詢。若要深入了解 Lakehouse 同盟，請參閱什麼是 Lakehouse 同盟？。

若要使用 Lakehouse Federation 連線到 Snowflake 資料庫，您必須在 Azure Databricks Unity Catalog 中繼資料存放區中建立下列項目：

與 Snowflake 資料庫的連接。
外部目錄，鏡像 Unity 目錄中的 Snowflake 資料庫，讓您可以使用 Unity 目錄查詢語法和數據控管工具來管理 Azure Databricks 使用者對資料庫的存取權。

開始之前

工作區需求：

計算需求：

從您的計算資源到目標資料庫系統的網路連線狀況。請參閱 Lakehouse 同盟的網路建議。
Azure Databricks 計算必須使用 Databricks Runtime 13.3 LTS 或更新版本，以及標準或 專用的 存取模式。
SQL 倉儲必須是專業或無伺服器，且必須使用 2023.40 或更新版本。

所需的權限：

若要建立連線，您必須是中繼存放區系統管理員，或是具有附加至工作區之 Unity 目錄中繼存放區 CREATE CONNECTION 許可權的使用者。
若要建立外部目錄，您必須在中繼存放區擁有 CREATE CATALOG 權限，並且必須是連線的擁有者，或在連線上擁有 CREATE FOREIGN CATALOG 權限。

在每個後續的任務導向章節中指定了額外的權限需求。

如果您打算使用 OAuth 進行驗證，請在 Snowflake 控制台中建立安全性整合。
如果您打算使用 OAuth 存取令牌進行驗證，您也必須要求存取令牌。

（選擇性）在 Snowflake 控制台中建立安全性整合

如果您想要使用 OAuth 進行驗證，請先遵循此步驟，再建立 Snowflake 連線。若要改用使用者名稱和密碼進行驗證，請略過本節。

注意

僅支援 Snowflake 的內建 OAuth 整合。不支援Okta或 Microsoft Entra識別碼之類的外部 OAuth 整合。

在 Snowflake 控制台中，執行 CREATE SECURITY INTEGRATION。取代下列值：

<integration-name>：您 OAuth 整合的唯一名稱。
<workspace-url>：Azure Databricks 工作區 URL。您必須將 OAUTH_REDIRECT_URI 設定為 https://<workspace-url>/login/oauth/snowflake.html，其中 <workspace-url> 是您將建立 Snowflake 連線之 Azure Databricks 工作區的唯一 URL。
<duration-in-seconds>：刷新令牌的時間長度。

重要

OAUTH_REFRESH_TOKEN_VALIDITY 是預設設為90天的自訂欄位。更新令牌到期之後，您必須重新驗證這個連線。將欄位設定為合理的時間長度。

CREATE SECURITY INTEGRATION <integration-name>
TYPE = oauth
ENABLED = true
OAUTH_CLIENT = custom
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://<workspace-url>/login/oauth/snowflake.html'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = <duration-in-seconds>
OAUTH_ENFORCE_PKCE = TRUE;

（選擇性）要求 OAuth 存取令牌

請遵循 Snowflake 知識庫中的指南：如何使用 Snowflake OAuth 來為自定義用戶端產生和使用 OAuth 令牌。

建立連線

連接會指定用來存取外部資料庫系統的路徑和認證。若要建立連線，您可以在 Azure Databricks 筆記本或 Databricks SQL 查詢編輯器中使用目錄總管或 CREATE CONNECTION SQL 命令。

注意

您也可使用 Databricks REST API 或 Databricks CLI 來建立連線。請參閱 POST /api/2.1/unity-catalog/connections 和 Unity Catalog 命令。

需要的權限：具有 CREATE CONNECTION 權限的中繼存放區系統管理員或使用者。

目錄瀏覽器

在 Azure Databricks 工作區中，單擊目錄。
在目錄窗格頂端，單擊新增圖標並從選單中選取 新增連線。

或者，從 [快速存取] 頁面，按兩下 [外部數據 >] 按鈕，移至 [連線] 索引卷標，然後按兩下 [建立連線]。
在 [連線基本概念] 頁面的 [設定連線 精靈] 中，輸入一個使用者易於記憶的 連線名稱。
請選擇 Snowflake 的 連線類型。
針對 [驗證類型]，請從下拉功能表中選取 [Username and password]、[OAuth access token]、[PEM Private Key] 或 [OAuth]。
(選擇性) 新增註解。
點選 [下一步] 。
輸入雪花倉儲的下列驗證和聯機詳細數據。您選取之驗證方法的特定屬性前面會加上括弧中的 Auth type。
- 主機：例如 snowflake-demo.east-us-2.azure.snowflakecomputing.com
- 埠：例如 443
- 使用者：例如 snowflake-user
- （基本身份驗證）密碼：例如，password123
- （OAuth 存取令牌）存取令牌：從存取令牌（可選）要求 OAuth 存取令牌。
- （OAuth 存取令牌）到期時間（以秒為單位）：來自（選擇性）請求的 OAuth 存取令牌的到期時間（expires_in）。
- （OAuth） 用戶端標識碼：在 Snowflake 控制台中，執行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') 以擷取安全性整合的用戶端識別碼。
- （OAuth） 客戶端密碼：在 Snowflake 控制台中，執行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') 以擷取安全性整合的客戶端密碼。
- （OAuth） OAuth 範圍：refresh_token session:role:<role-name>。指定要在<role-name>中使用的Snowflake角色。
- （OAuth） 使用 Snowflake 登入：按兩下並使用您的 OAuth 認證登入 Snowflake。
- （PEM 私鑰） PEM 私鑰：來自 RSA 金鑰對的私鑰，格式為 HEX64。
- （PEM 私鑰）以秒為單位到期：使用私鑰建立之連線的到期時間（以秒為單位）。
  
  成功登入時，系統會將您導向回 設定連線 精靈。
點選 「建立連線」。
（基本身份驗證）在 [連線詳細數據] 頁面上，指定下列項目：
- 雪花倉儲：例如 my-snowflake-warehouse
- （選擇性）代理主機：用來連線到 Snowflake 的代理主機。您也必須選取 [使用代理伺服器]，並指定 代理伺服器連接埠。
- （選擇性）使用代理：是否要使用代理伺服器連線到 Snowflake。
- （選擇性） Proxy 埠：用來連線到 Snowflake 的 Proxy 埠。您也必須選取 [使用代理伺服器] 並指定 代理伺服器主機。
- （選擇性） Snowflake 角色：連線後要用於會話的預設安全性角色。
點選 [下一步] 。
在 目錄基本頁面 上，輸入外來目錄的名稱。外部目錄會鏡像外部數據系統中的資料庫，讓您可以使用 Azure Databricks 和 Unity 目錄來查詢和管理該資料庫中數據的存取權。
（選擇性）按兩下 [ 測試連線 ] 以確認其運作正常。
點選 「建立目錄」。
在 [Access] 頁面上，選擇允許使用者存取您所建立的目錄的工作區。您可以選取 [所有工作區都有存取權]，或點擊 [指派給工作區]，選取工作區，然後點擊 [指派]。
將 擁有者 變更為可以管理目錄中所有物件存取權的人。在文字框中開始輸入對象，然後在搜尋結果中點擊該對象。
在目錄上授予 許可權。請點擊授與：
1. 指定主體誰可以存取目錄中的物件。在文字框中開始輸入對象，然後在搜尋結果中點擊該對象。
2. 選取 許可權預設，以授與每個主體。根據預設，所有帳戶用戶都會被授與 BROWSE。
  - 從下拉功能表中選取 [數據讀取器]，以授與目錄中物件 read 許可權。
  - 從下拉功能表中選取 [數據編輯器]，以授與目錄中物件的 read 和 modify 許可權。
  - 手動選取要授與的許可權。
3. 點擊授與。
點選 [下一步] 。
在 [元數據] 頁面上，指定標籤的鍵-值配對。如需詳細資訊，請參閱將標籤套用至 Unity Catalog 可保護的物件。
(選擇性) 新增註解。
點選 [儲存]。

SQL

在筆記本或 Databricks SQL 查詢編輯器中執行下列命令。

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  password '<password>'
);

我們建議您使用 Azure Databricks 秘密，而非使用純文本字串來儲存如憑證等敏感值。例如：

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>')
)

如需設定祕密的相關資訊，請參閱祕密管理。

建立外國目錄

注意

如果您使用使用者介面來建立資料來源的連線，則會包含外部目錄的建立，且您可以略過此步驟。

外部目錄會鏡像外部數據系統中的資料庫，讓您可以使用 Azure Databricks 和 Unity 目錄來查詢和管理該資料庫中數據的存取權。若要建立外部目錄，您可以使用已定義的數據源連線。

若要建立外部目錄，您可以在 Azure Databricks 筆記本或 SQL 查詢編輯器中使用目錄總管或 CREATE FOREIGN CATALOG SQL 命令。您也可以使用 Databricks REST API 或 Databricks CLI 來建立目錄。請參閱 POST /api/2.1/unity-catalog/catalogs 和 Unity Catalog 命令。

必要權限：對中繼存放區的CREATE CATALOG 權限，以及對連線的所有權或對連線的CREATE FOREIGN CATALOG 權限。

目錄瀏覽器

在 Azure Databricks 工作區中，按兩下目錄，以開啟 [目錄總管]。
在目錄窗格頂端，按一下新增圖示，然後從功能表中選取 新增目錄。

或者，從 [快速存取] 頁面，按一下 [目錄] 按鈕，然後按一下 [建立目錄] 按鈕。
請遵循在建立目錄中建立外部目錄的指示。

SQL

在筆記本或 SQL 查詢編輯器中，執行下列 SQL 命令。括弧中的項目是選擇性的。替換佔位符值：

<catalog-name>：Azure Databricks 中目錄的名稱。
<connection-name>：指定數據源、路徑和存取認證的連接物件。
<database-name>：您想要在 Azure Databricks 中作為目錄鏡像的資料庫名稱。

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (database '<database-name>');

區分大小寫的資料庫識別碼

外部目錄的 [database] 字段會對應至 Snowflake 資料庫識別碼。如果 Snowflake 資料庫識別碼不區分大小寫，那麼您在外部目錄 <database-name> 中使用的大小寫將會被保留。不過，如果 Snowflake 資料庫識別符區分大小寫，您必須將外部目錄 <database-name> 用雙引號括起來，以保留大小寫。

例如：

database 已轉換成 DATABASE
"database" 已轉換成 database
"database""" 已轉換成 database"

若要逸出雙引號，請使用另一個雙引號。
"database"" 會導致錯誤，因為雙引號未正確轉義。

如需詳細資訊，請參閱 Snowflake 檔中的標識符需求。

支援的下推策略

支援以下下推功能：

篩選
預測
限制
聯結
匯總函數（Average、Corr、CovPopulation、CovSample、Count、Max、Min、StddevPop、StddevSamp、Sum、VariancePop、VarianceSamp）
函式（字串函式、數學函式、數據、時間和時間戳函式，以及其他函式，例如 Alias、Cast、SortOrder）
Windows 函式（DenseRank、Rank、RowNumber）
排序

資料類型對應

當您從 Snowflake 讀取至 Spark 時，資料類型會對應如下：

雪花類型	Spark 類型
小數、數字、數值	十進制類型 (DecimalType)
大數據型整數、字節整數、整數、整數、小整數、微整數	整數型別
float、float4、float8	浮點類型
雙精度、雙倍精度、實數	DoubleType
char， character， string， text， time， varchar	字串類型
二進制	二進制類型
boolean	BooleanType
日期	日期類型
datetime、timestamp、timestamp_ltz、timestamp_ntz、timestamp_tz	時間戳類型

OAuth 限制

以下是 OAuth 支援限制：

Snowflake OAuth 端點必須可從 Databricks 控制平面 IP 存取。請參閱從 Azure Databricks 控制平面輸出。 Snowflake 支援在安全性整合層級設定網路原則，以允許個別的網路原則，以便從 Databricks 控制平面直接連線到 OAuth 端點進行授權。
不支援使用 Proxy、 Proxy 主機、 Proxy 埠和 Snowflake 角色設定選項。指定 Snowflake 角色 作為 OAuth 範圍的一部分。

PEM 私密鑰限制

以下是 PEM 私密鑰支援限制：

Snowflake JDBC 驅動程式不支援使用加密私鑰進行驗證。若要避免錯誤，請產生已新增 -nocrypt 選項的金鑰，如下所示：
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```

其他資源

請參閱 Snowflake 檔中的下列文章：

共用方式為

在 Snowflake 上執行同盟查詢

開始之前

（選擇性）在 Snowflake 控制台中建立安全性整合

（選擇性）要求 OAuth 存取令牌

建立連線

目錄瀏覽器

SQL

建立外國目錄

目錄瀏覽器

SQL

區分大小寫的資料庫識別碼

支援的下推策略

資料類型對應

OAuth 限制

PEM 私密鑰限制

其他資源

意見反應

其他資源