搭配 Azure Databricks 使用 SQLAlchemy
Azure Databricks 為 Azure Databricks 提供 SQLAlchemy 方言 (SQLAlchemy 用來與各種類型的資料庫 API 實作和資料庫通訊的系統)。 SQLAlchemy 是 Python SQL 工具組和物件關聯式對應 (ORM)。 SQLAlchemy 提供一套知名的企業級持續性模式，專為高效且高效能的資料庫存取而設計，並改編成簡單的 Pythonic 網域語言。 請參閱功能和理念。
適用於 Azure Databricks 的 SQLAlchemy 方言隨附適用於 Python 的 Databricks SQL 連接器。 本文涵蓋適用於 Azure Databricks 2.0 版的 SQLAlchemy 方言，而這就需要適用於 Python 3.0.0 版或更新版本的 Databricks SQL 連接器。
需求
- 執行 Python >=3.8 和 <=3.11 的開發機器。
- Databricks 建議您使用 Python 虛擬環境，例如 Python 隨附的 venv 所提供的環境。 虛擬環境可協助您確保同時使用正確的 Python 版本和適用於 Python 的 Databricks SQL 連接器。 設定和使用虛擬環境不屬於本文的討論範圍。 如需詳細資訊，請參閱建立虛擬環境。
- 現有的叢集或 SQL 倉儲。
開始使用
透過執行
pip install "databricks-sql-connector[sqlalchemy]"或python -m pip install "databricks-sql-connector[sqlalchemy]"，在您的開發電腦上安裝適用於 Python 程式庫 3.0.0 版或更新版本的 Databricks SQL 連接器。 如需版本資訊，請參閱 databricks-sql-connector 版本歷程記錄。針對想要使用的叢集或 SQL 倉儲，收集下列資訊：
Cluster
- 叢集的伺服器主機名稱。 您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [伺服器主機名稱] 值取得此值。
- 叢集的 HTTP 路徑。 您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [HTTP 路徑] 值取得此值。
SQL 倉儲
驗證
適用於 Azure Databricks 的 SQLAlchemy 方言支援 Azure Databricks 個人存取權杖驗證。
若要建立 Azure Databricks 個人存取權杖，請執行以下操作：
- 在 Azure Databricks 工作區中，按一下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取使用者設定。
- 按一下 [開發人員]。
- 在 [存取權杖] 旁，按一下 [管理]。
- 按一下 產生新權杖。
- (選擇性) 輸入可協助您之後識別此權杖的註解，並變更權杖的預設存留期 90 天。 若要建立沒有存留期的權杖 (不建議)，請將 [存留期 (天)] 方塊留空 (空白)。
- 按一下 產生。
- 將顯示的權杖複製到安全位置，然後選取 [完成]。
注意
請務必將複製的權杖儲存在安全位置。 請勿與其他人共用複製的權杖。 如果您遺失複製的權杖，就無法重新產生完全相同的權杖。 相反地，您必須重複此程序來建立新的權杖。 如果您遺失複製的權杖，或您認為權杖已遭入侵，Databricks 強烈建議您按一下 [存取權杖] 頁面上權杖旁邊的垃圾桶 (撤銷) 圖示，立即從工作區中刪除該權杖。
注意：如果您無法在工作區中建立或使用 PAT，這可能是因為您的工作區系統管理員已停用權杖，或未授與您建立或使用權杖的權限。 請諮詢您的工作區系統管理員或參閱下列主題：
若要驗證 SQLAlchemy 方言，請使用下列程式碼片段。 此片段假設您已設定下列環境變數：
DATABRICKS_TOKEN，設定為 Azure Databricks 個人存取權杖。- 將
DATABRICKS_SERVER_HOSTNAME設定為叢集或 SQL 倉儲的 [伺服器主機名稱] 值。 DATABRICKS_HTTP_PATH，設定為叢集或 SQL 倉儲的 HTTP 路徑 值。DATABRICKS_CATALOG，設定為 Unity 目錄中的目標目錄。DATABRICKS_SCHEMA，設定為 Unity 目錄中的目標結構描述 (也稱為資料庫)。
若要設定環境變數，請參閱您的作業系統文件。
import os
from sqlalchemy import create_engine
access_token = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path = os.getenv("DATABRICKS_HTTP_PATH")
catalog = os.getenv("DATABRICKS_CATALOG")
schema = os.getenv("DATABRICKS_SCHEMA")
engine = create_engine(
url = f"databricks://token:{access_token}@{server_hostname}?" +
f"http_path={http_path}&catalog={catalog}&schema={schema}"
)
# ...
您可以使用上述 engine 變數，透過 Azure Databricks 計算資源連線到指定的目錄和結構描述。 如需連線範例，請參閱下一節和 GitHub 中的 sqlalchemy.py 檔案。
範例
請參閱 GitHub 中的 sqlalchemy.py 檔案。
DBAPI 參考
- 請參閱 GitHub 中的 README.sqlalchemy.md 檔案。
- 另請參閱 GitHub 中的 sqlalchemy 原始程式碼目錄。