连接到 dbt Core

dbt（数据编译工具）是一种开发环境，它使数据分析师和数据工程师能够通过编写 select 语句来转换数据。 dbt 可将这些 select 语句转换为表和视图。 dbt 将代码编译为原始 SQL，然后在 Azure Databricks 中指定的数据库上运行该代码。 dbt 支持版本控制、文档、模块化等协作编码模式和最佳做法。

dbt 不会提取或加载数据。 dbt 使用“加载后转换”体系结构，仅专注于转换步骤。 dbt 假定数据库中已有数据的副本。

本文重点介绍如何使用 dbt Core。 dbt Core 使你能够在本地开发计算机上所选的文本编辑器或 IDE 中编写 dbt 代码，然后从命令行运行 dbt。 dbt Core 包括 dbt 命令行接口 (CLI)。 dbt CLI 是一个免费的开放源代码工具。

也可使用名为 dbt Cloud 的托管版本 dbt。 dbt Cloud 为计划作业、CI/CD、提供文档、监视和警报以及集成开发环境 (IDE) 提供统包支持。 有关详细信息，请参阅连接到 dbt Cloud。 dbt Cloud 开发人员计划提供一个免费的开发人员席位；此外，也可以使用团队和企业付费计划。 有关详细信息，请参阅 dbt 网站上的 dbt 定价。

由于 dbt Core 和 dbt Cloud 可以使用托管的 git 存储库（例如，在 GitHub、GitLab 或 BitBucket 上），因此可以使用 dbt Core 创建 dbt 项目，然后使其可供 dbt Cloud 用户使用。 有关详细信息，请参阅 dbt 网站上的创建 dbt 项目和使用现有项目。

要求

安装 dbt Core 之前，必须在本地开发计算机上安装以下工具：

• Python 3.7 或更高版本
• 用于创建 Python 虚拟环境的实用工具（例如 pipenv）

还需要使用以下方法之一进行身份验证：

• （推荐）dbt Core 在帐户中作为 OAuth 应用程序启用。 此项已默认启用。

• 个人访问令牌

  注意

  使用自动化工具、系统、脚本和应用进行身份验证时，Databricks 建议 OAuth 令牌，这是一种安全最佳做法。

  如果使用个人访问令牌身份验证，Databricks 建议使用属于服务主体（而不是工作区用户）的个人访问令牌。 若要为服务主体创建令牌，请参阅管理服务主体的令牌。

步骤1：创建并激活 Python 虚拟环境

在本步骤中，需要使用 pipenv 创建 pipenv 。 建议使用 Python 虚拟环境，因为它将包版本和代码依赖项隔离到该特定环境，而不管其他环境中的包版本和代码依赖项。 这有助于减少意外的包版本不匹配和代码依赖项冲突。

1. 从终端切换到空目录，然后创建该目录（如有必要）。 此过程会在用户主目录的根目录中创建名为 dbt_demo 的空目录。

   Unix、linux、macos

   mkdir ~/dbt_demo
   cd ~/dbt_demo
   

   Windows

   mkdir %USERPROFILE%\dbt_demo
   cd %USERPROFILE%\dbt_demo
   

2. 在空目录中，创建包含以下内容的名为 Pipfile 的文件。 此 Pipfile 指示 pipenv 使用 Python 版本 3.8.6。 如果使用不同的版本，请将 3.8.6 替换为版本号。

   [[source]]
   url = "https://pypi.org/simple"
   verify_ssl = true
   name = "pypi"
   
   [packages]
   dbt-databricks = "*"
   
   [requires]
   python_version = "3.8.6"
   

   注意

   上面的行 dbt-databricks = "*" 指示 pipenv 使用最新版本的 dbt-databricks 包。 在生产方案中，应将 * 替换为你要使用的特定版本的包。 Databricks 建议使用 dbt-databricks 包的 1.6.0 或更高版本。 请参阅 Python 包索引 (PyPI) 网站上的 dbt-databricks 发行历史记录。

3. 通过运行 pipenv 并指定要使用的 Python 版本，在此目录中创建 Python 虚拟环境。 此命令指定 Python 版本 3.8.6。 如果使用不同的版本，请将 3.8.6 替换为版本号：

   pipenv --python 3.8.6
   

4. 结合 install 选项运行 pipenv 来安装 dbt Databricks 适配器。 这会在 Pipfile 中安装包，其中包括来自 PyPI 的 dbt Databricks 适配器包 dbt-databricks。 dbt Databricks 适配器包会自动安装 dbt Core 和其他依赖项。

   重要

   如果本地开发计算机使用以下任何操作系统，则必须先完成附加步骤：CentOS、MacOS、Ubuntu、Debian 和 Windows。 请参阅 dbt Labs 网站上的使用 pip 安装 dbt 中的“我的操作系统是否需要满足先决条件”部分。

   pipenv install
   

5. 通过运行 pipenv shell 激活此虚拟环境。 为了确认激活，终端会在提示符之前显示 (dbt_demo)。 虚拟环境开始使用指定版本的 Python，并隔离此新环境中的所有包版本和代码依赖项。

   pipenv shell
   

   注意

   若要停用此虚拟环境，请运行 exit。 (dbt_demo) 从提示符之前消失。 如果在停用此虚拟环境的情况下运行 python --version 或 pip list，则可能会看到不同版本的 Python 和/或不同的可用包或包版本列表。

6. 使用 --version 选项运行 python，确认虚拟环境正在运行预期的 Python 版本。

   python --version
   

   如果显示意外的 Python 版本，请确保通过运行 pipenv shell 激活虚拟环境。

7. 结合 --version 选项运行 dbt，确认虚拟环境正在运行预期的 dbt 和 dbt Databricks 适配器版本。

   dbt --version
   

   如果显示了意外的 dbt 或 dbt Databricks 适配器版本，请确保运行 pipenv shell 来激活虚拟环境。 如果仍显示意外版本，请尝试在激活虚拟环境后再次安装 dbt 或 dbt Databricks 适配器。

步骤 2：创建 dbt 项目并指定和测试连接设置

在本步骤中，需要创建一个 dbt 项目（即需要使用 dbt 的相关目录和文件的集合）。 然后，配置连接配置文件，其中包含与 Azure Databricks 群集和/或 SQL 仓库的连接设置。 为了增强安全性，默认情况下 dbt 项目和配置文件存储在不同的位置。

1. 在虚拟环境仍处于激活状态的情况下，结合项目的名称运行 dbt init 命令。 此过程创建名为 my_dbt_demo 的项目。

   dbt init my_dbt_demo
   

2. 当系统提示选择是使用 databricks 还是 spark 数据库时，请输入对应于 databricks 的数字。

3. 当系统提示输入 host 值时，请执行以下操作：

   • 对于群集，请输入 Azure Databricks 群集的“高级选项 > JDBC/ODBC”选项卡中的“服务器主机名”值。
   • 对于 SQL 仓库，请输入 SQL 仓库的连接详细信息选项卡中的“服务器主机名”值。

4. 当系统提示输入 http_path 值时，请执行以下操作：

   • 对于群集，请输入 Azure Databricks 群集的“高级选项 > JDBC/ODBC”选项卡中的“HTTP 路径”值。
   • 对于 SQL 仓库，请输入 SQL 仓库的连接详细信息选项卡中的“HTTP 路径”值。

5. 若要选择身份验证类型，请输入 use oauth（推荐）或 use access token 对应的数字。

6. 如果为身份验证类型选择了 use access token，请输入 Azure Databricks 个人访问令牌的值。

   注意

   作为安全最佳做法，在使用自动化工具、系统、脚本和应用进行身份验证时，Databricks 建议使用属于服务主体（而不是工作区用户）的个人访问令牌。 若要为服务主体创建令牌，请参阅管理服务主体的令牌。

7. 当系统提示输入 desired Unity Catalog option 值时，输入与 use Unity Catalog 或 not use Unity Catalog 对应的数字。

8. 如果选择使用 Unity Catalog，请在出现提示时输入 catalog 所需的值。

9. 出现提示时，请输入 schema 和 threads 的所需值。

10. dbt 将条目写入 profiles.yml 文件。 dbt init 命令的输出中列出了此文件的位置。 以后还可通过运行 dbt debug --config-dir 命令列出此位置。 现在可以打开此文件来检查并验证其内容。

    如果选择了 use oauth 作为身份验证类型，请将计算机到计算机 (M2M) 或用户到计算机 (U2M) 身份验证配置文件添加到 profiles.yml。

    例如，请参阅使用 Microsoft Entra ID 从 dbt Core 配置 Azure Databricks 登录。

    Databricks 不建议直接在 profiles.yml 中指定机密， 而是将客户端 ID 和客户端密码设置为环境变量。

11. 通过遍历 my_dbt_demo 目录并运行 dbt debug 命令来确认连接详细信息是否正确。

    如果为身份验证类型选择了 use oauth，系统会提示你使用标识提供者身份登录。

    重要

    在开始之前，请验证你的群集或 SQL 仓库是否正在运行。

    应该会看到与下面类似的输出：

    cd my_dbt_demo
    dbt debug
    

    ...
    Configuration:
      profiles.yml file [OK found and valid]
      dbt_project.yml file [OK found and valid]
    
    Required dependencies:
      - git [OK found]
    
    Connection:
      ...
      Connection test: OK connection ok
    

后续步骤

• 在本地创建、运行和测试 dbt Core 模型。 请参阅 dbt Core 教程。

其他资源

• dbt 具体是什么？
• dbt 网站上的适用于所有人的分析工程：dbt Cloud 中的 Databricks。
• dbt 入门教程
• dbt 文档
• dbt CLI 文档
• dbt + Databricks 演示
• dbt Discourse 社区
• dbt 博客