通过

将 SQLAlchemy 与 Azure Databricks 配合使用

  • 项目

Azure Databricks 提供专用于 Azure Databricks 的 SQLAlchemy方言（这是 SQLAlchemy 用于与各种类型的数据库 API 实现和数据库通信的系统）。 SQLAlchemy 是 Python SQL 工具包和对象关系映射器 (ORM)。 SQLAlchemy 提供了一整套众所周知的企业级持久性模式，旨在实现高效且高性能的数据库访问，并采用简单的 Pythonic 域语言。 请参阅特征和理念。

需要安装 Azure Databricks 的 SQLAlchemy 方言才能将 SQLAlchemy 功能与 Azure Databricks 配合使用。 本文介绍适用于 Azure Databricks 版本 1.0 和 2.0 的 SQLAlchemy 方言，该方言将基于用于 Python 4.0.0 或更高版本的 Databricks SQL 连接器。

要求

  • 运行 Python >=3.8 和<=3.11 的开发计算机。
  • Databricks 建议使用 Python 虚拟环境，例如 python 随附的 venv 提供的环境。 虚拟环境有助于确保同时使用正确版本的 Python 和适用于 Python 的 Databricks SQL 连接器。 设置和使用虚拟环境不在本文的讨论范围之内。 有关详细信息，请参阅创建虚拟环境。
  • 现有群集或 SQL 仓库。

入门

  • 请使用 pip install databricks-sqlalchemy~=1.0（针对 SQLAlchemy v1）或 pip install databricks-sqlalchemy（针对 SQLAlchemy v2）安装 databricks-sqlalchemy。 有关版本信息，请参阅 databricks-sqlalchemy 发布历史记录。

  • 收集想要使用的群集或 SQL 仓库的以下信息：

    群集

    • 群集的服务器主机名。 从您群集的“高级选项”> JDBC/ODBC选项卡中的“服务器主机名”值可以获取此信息。
    • 群集的 HTTP 路径。 从群集的>选项卡的“HTTP 路径”值中可以获取此路径。

    SQL 仓库

    • SQL 仓库的服务器主机名。 您可以从 SQL 仓库的“连接详细信息”选项卡中的“服务器主机名”值中获取此信息。
    • SQL 仓库的 HTTP 路径。 从 SQL 仓库的“连接详细信息”选项卡的“HTTP 路径”值中可以获取此路径。

身份验证

Azure Databricks 的 SQLAlchemy 方言支持 Azure Databricks 个人访问令牌身份验证。

要创建 Azure Databricks 个人访问令牌，请遵循适用于工作区用户的 Azure Databricks 个人访问令牌中的步骤。

要对 SQLAlchemy 方言进行身份验证，请使用以下代码片段。 此代码片段假定你已设置以下环境变量：

  • DATABRICKS_TOKEN，设置为 Azure Databricks 个人访问令牌。
  • DATABRICKS_SERVER_HOSTNAME，设置为群集或 SQL 仓库的“服务器主机名”值。
  • DATABRICKS_HTTP_PATH，设置为群集或 SQL 仓库的“HTTP 路径”值。
  • DATABRICKS_CATALOG，设置为 Unity Catalog 中的目标目录。
  • DATABRICKS_SCHEMA，设置为 Unity Catalog 中的目标架构（也称为数据库）。

若要设置环境变量，请参阅操作系统的文档。

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 计算资源连接到指定的目录和架构。

SQLAlchemy v1

有关连接示例，请参阅此 example.py

SQLAlchemy v2

有关连接示例，请参阅以下部分和 GitHub 中的 sqlalchemy_example.py 文件。

DBAPI 参考

其他资源