在 Snowflake 上執行同盟查詢

發行項
08/05/2024

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

若要使用 Lakehouse 同盟連線到 Snowflake 資料庫，您必須在 Azure Databricks Unity 目錄中繼存放區中建立下列專案：

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

開始之前

工作區需求：

計算需求：

從 Databricks 執行時間叢集或 SQL 倉儲到目標資料庫系統的網路連線。請參閱 Lakehouse 同盟的網路建議。
Azure Databricks 叢集必須使用 Databricks Runtime 13.3 LTS 或更新版本，以及共用或單一使用者存取模式。
SQL 倉儲必須是 Pro 或無伺服器，且必須使用 2023.40 或更新版本。

所需的權限：

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

後續每個以工作為基礎的區段會指定其他許可權需求。

如果您打算使用 OAuth 進行驗證，請在 Snowflake 控制台中建立安全性整合。如需詳細資訊，請參閱下一節。

（選擇性）在 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;

建立連線

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

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

目錄總管

在您的 Azure Databricks 工作區中，按兩下 [目錄]。
在 [目錄] 窗格頂端，單擊 [新增] 圖示，然後從功能表中選取 [新增聯機]。

或者，從 [快速存取] 頁面，按兩下 [外部數據] 按鈕，移至 [連線] >索引標籤，然後按兩下 [建立連線]。
輸入使用者易記 的連線名稱。
選取 Snowflake 的 [連線類型]。
輸入 Snowflake 倉儲的下列連線屬性。
- 驗證類型： OAuth 或 Username and password
- 主機：例如 snowflake-demo.east-us-2.azure.snowflakecomputing.com
- 埠：例如 443
- 雪花倉儲：例如 my-snowflake-warehouse
- 使用者：例如 snowflake-user
- （OAuth） 用戶端標識碼：在 Snowflake 控制台中，執行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security_integration_name>') 以擷取安全性整合的用戶端標識碼。
- （OAuth）： 客戶端密碼：在 Snowflake 控制台中，執行 SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security_integration_name>') 以擷取安全性整合的客戶端密碼。
- （OAuth） 用戶端範圍： refresh_token session:role:<role-name>。指定要在中使用的 <role-name>Snowflake 角色。
- （使用者名稱與密碼）密碼：例如 password123
（OAuth）系統會提示您使用 OAuth 認證登入 Snowflake。
（選擇性）按兩下 [ 測試連線 ] 以確認其運作正常。
（選擇性）新增批注。
按一下 [建立]。

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 命令。

必要許可權：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 類型
decimal、number、numeric	DecimalType
bigint、byteint、int、integer、smallint、tinyint	IntegerType
float、float4、float8	FloatType
double、double precision、real	DoubleType
char， character， string， text， time， varchar	StringType
binary	BinaryType
boolean	BooleanType
date	DateType
datetime、timestamp、timestamp_ltz、timestamp_ntz、timestamp_tz	TimestampType

OAuth 限制

以下是 OAuth 支援限制：

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

其他資源

在 Snowflake 檔中為自訂用戶端設定 Snowflake OAuth
SQL 參考：Snowflake 檔中的 CREATE SECURITY INTEGRATION （Snowflake OAuth）

共用方式為

在 Snowflake 上執行同盟查詢

開始之前

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

建立連線

目錄總管

SQL

建立外部目錄

目錄總管

SQL

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

支援的下推

資料類型對應

OAuth 限制

其他資源

意見反應

其他資源