教程：开始使用 Snowflake 上的 dbt 项目¶

简介¶

本教程指导您创建一个 dbt Projects on Snowflake 的工作区，并将其连接到 GitHub 存储库，该存储库是您从 getting-started-with-dbt-on-snowflake 存储库 (https://github.com/Snowflake-Labs/getting-started-with-dbt-on-snowflake) 中分叉而来的然后，您可以使用工作区更新 dbt 项目文件，测试和运行 dbt 项目，该项目将 dbt 项目的数据模型输出具体化到目标 Snowflake 数据库和架构中。部署该项目是为了在 Snowflake 上创建 dbt 项目对象。最后，您可以设置一项任务，按照您定义的计划执行项目。

设置环境¶

完成以下步骤，为本教程设置环境：

1. 分叉并克隆 dbt Projects on Snowflake 入门存储库

2. （可选）创建用于执行工作区操作的仓库

3. 为集成和模型物化创建数据库和架构

4. 在 Snowflake 中创建用于连接 GitHub 的 API 集成

5. 在 Snowflake 中为 dbt 依赖关系创建外部访问集成

CREATE WAREHOUSE tasty_bytes_dbt_wh WAREHOUSE_SIZE = XLARGE;

CREATE DATABASE tasty_bytes_dbt_db;
CREATE SCHEMA tasty_bytes_dbt_db.integrations;
CREATE SCHEMA tasty_bytes_dbt_db.dev;
CREATE SCHEMA tasty_bytes_dbt_db.prod;

USE tasty_bytes_dbt_db.integrations;
CREATE OR REPLACE SECRET tasty_bytes_dbt_db.integrations.tb_dbt_git_secret
  TYPE = password
  USERNAME = 'your-gh-username'
  PASSWORD = 'YOUR_PERSONAL_ACCESS_TOKEN';

CREATE OR REPLACE API INTEGRATION tb_dbt_git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://github.com/my-github-account')
  -- Comment out the following line if your forked repository is public
  ALLOWED_AUTHENTICATION_SECRETS = (tasty_bytes_dbt_db.integrations.tb_dbt_git_secret)
  ENABLED = TRUE;

-- Create NETWORK RULE for external access integration

CREATE OR REPLACE NETWORK RULE dbt_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  -- Minimal URL allowlist that is required for dbt deps
  VALUE_LIST = (
    'hub.getdbt.com',
    'codeload.github.com'
    );

-- Create EXTERNAL ACCESS INTEGRATION for dbt access to external dbt package locations

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION dbt_ext_access
  ALLOWED_NETWORK_RULES = (dbt_network_rule)
  ENABLED = TRUE;

创建连接到 Git 存储库的工作区¶

在此步骤中，您将在 Snowsight 中创建一个连接到 GitHub 存储库的工作区。有关工作区的更多信息，请参阅 工作区。

1. 登录 Snowsight。

2. 在左侧导航菜单中，选择 Projects » 工作区。

3. 在工作区文件区域上方的工作区列表中，在 Create Workspace 下方选择 From Git repository。（工作区列表的默认选择是 My Workspace。）

4. 对于 Repository URL，输入您的分叉 GitHub 存储库的 SSH URL；例如，https://github.com/my-github-account/getting-started-with-dbt-on-snowflake.git

5. 对于 Workspace name，输入名称。在本教程的后面部分，我们将使用 tasty_bytes_dbt。

6. 在 API integration 下方，选择您之前创建的 API 集成的名称；例如，TB_DBT_GIT_API_INTEGRATION。

7. 如果您的 GitHub 存储库是公共，请选择 Public repository，然后选择 Create。

   备注

   工作区不支持将变更从工作区提交和推送到公共存储库。

8. 如果您的 GitHub 存储库是专用的，并且您在设置期间为 API 集成创建了密钥，请执行以下步骤：

   1. 选择 Personal access token。

   2. 在 Credentials secret 下，选择 Select database and schema。

   3. 从列表中选择数据库（例如，TASTY_BYTES_DBT_DB），然后从存储 API 集成的列表（例如，INTEGRATIONS）中选择架构。

   4. 选择 Select secret，然后从列表中选择您的密钥；例如，tb_dbt_git_secret。

9. 选择 Create。

   Snowflake 连接到您指定的 GitHub 存储库并打开您的新工作区。工作区中名为 tasty_bytes_dbt_demo 的单个文件夹包含您将要使用的 dbt 项目。

tasty_bytes:
target: dev
outputs:
  dev:
    type: snowflake
    account: 'not needed'
    user: 'not needed'
    role: accountadmin
    database: tasty_bytes_dbt_db
    schema: dev
    warehouse: tasty_bytes_dbt_wh
  prod:
    type: snowflake
    account: 'not needed'
    user: 'not needed'
    role: accountadmin
    database: tasty_bytes_dbt_db
    schema: prod
    warehouse: tasty_bytes_dbt_wh

运行 tasty_bytes_setup.sql 中的 SQL 命令来设置源数据¶

作为其转换的源数据，存储库中的 dbt 项目使用虚构的 Tasty Bytes 餐车品牌的基础数据模型。用于创建数据模型的 SQL 脚本位于工作区中。

1. 在您的工作区中，导航到 tasty_bytes_dbt_demo/setup/tasty_bytes_setup.sql 文件，然后将其打开。

2. 从工作区编辑器右上角的上下文选择器中，选择您之前创建的仓库；例如，TASTY_BYTES_DBT_WH。

3. SQL 文件包含您在本教程中已经运行的命令。在文件开头附近，找到以下命令，然后将其注释掉，以避免再次运行它们并创建重复的资源：

   CREATE OR REPLACE WAREHOUSE ...;
   CREATE OR REPLACE API INTEGRATION ...;
   CREATE OR REPLACE NETWORK RULE ...;
   CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION ...;
   

   Copy

4. 运行文件中未注释的 SQL 命令。

   小技巧

   使用 cmd + Shift + Enter 来运行所有未注释的命令。

   Output 选项卡显示以下消息：

   tb_101 setup is now complete

ALTER SCHEMA tasty_bytes_dbt_db.dev SET LOG_LEVEL = 'INFO';
ALTER SCHEMA tasty_bytes_dbt_db.dev SET TRACE_LEVEL = 'ALWAYS';
ALTER SCHEMA tasty_bytes_dbt_db.dev SET METRIC_LEVEL = 'ALL';

ALTER SCHEMA tasty_bytes_dbt_db.prod SET LOG_LEVEL = 'INFO';
ALTER SCHEMA tasty_bytes_dbt_db.prod SET TRACE_LEVEL = 'ALWAYS';
ALTER SCHEMA tasty_bytes_dbt_db.prod SET METRIC_LEVEL = 'ALL';

为您的项目执行 dbt deps 命令¶

您可以使用工作区为项目执行常用的 dbt 命令。有关可用命令的列表，请参阅 支持的 dbt 命令。要运行命令，请从工作区编辑器上方的列表中选择 dbt Project、Profile 和 dbt 命令。然后，选择执行按钮。使用执行按钮旁边的向下箭头指定 dbt 命令支持的其他实参。

当您在工作区内执行任何 dbt 命令时，Output 选项卡会显示在 Snowflake 上执行的命令（绿色）以及该命令的标准输出，以便您可以监控命令的成功或失败。

对于任何 dbt 项目，必须执行的第一个命令是 deps，它会更新在项目 packages.yml 文件中指定的项目的依赖关系。除非更新了依赖关系，否则其他命令将失败。有关更多信息，请参阅 dbt 依赖关系。

1. 在工作区编辑器下方，打开 Output 选项卡，以便在从工作区运行 dbt 命令后可以看到标准输出。

2. 在工作区编辑器上方的菜单栏中，确认已选择默认 Project (tasty_bytes_dbt_demo)。您可以选择任何一个 Profile。该项目有 profiles.yml 文件中定义的配置文件 dev 和 prod。

3. 选择 Profile 列表，然后选择 启用次要角色，为该项目和此会话启用次要角色。

   备注

   在每次 Snowsight 会话期间，必须首先启用次要角色才能为每个项目运行 dbt 命令。可以将 Enterprise Edition 账户配置为对于特定用户或所有用户不允许次要角色。有关更多信息，请参阅 每个项目、每个会话都需要次要角色。

4. 在命令列表中，选择 Deps。

5. 在执行按钮旁边，选择向下箭头。

6. 在 dbt Deps 窗口中，保持 Run with defaults 选中状态，然后在提供的空白处输入您在安装期间创建的 External Access Integration 名称；例如，dbt_ext_access。

7. 要运行该命令，请选择 Deps。

   Output 选项卡显示在 Snowflake 上运行的 SQL 命令，类似于以下内容：

   execute dbt project from workspace "USER$"."PUBLIC"."tasty_bytes_dbt" project_root='tasty_bytes_dbt_demo' args='deps --target dev' external_access_integrations = (dbt_ext_access)
   

   Copy

   命令完成后，将显示类似于以下内容的标准输出消息：

   14:47:19  Running with dbt=1.8.9
   14:47:19  Updating lock file in file path: /tmp/dbt/package-lock.yml
   14:47:19  Installing dbt-labs/dbt_utils
   14:47:19  Installed from version 1.3.0
   14:47:19  Up to date!
   Uploading /tmp/dbt/package-lock.yml to snow://workspace/USER$ADMIN.PUBLIC."tasty_bytes_dbt"/versions/live/dbt//package-lock.yml
   

   package_lock.yml 文件已创建并显示在您的工作区文件列表中，旁边有一个 A。这表示该文件已新增到您的 dbt 项目的工作区中，其内容与以下示例类似：

   packages:
     - package: dbt-labs/dbt_utils
       version: 1.3.0
   

   Copy

编译 dbt 项目，查看 DAG，并查看已编译的 SQL¶

在 dbt 中编译项目可根据建模 SQL 文件创建可执行的 SQL 文件，并在工作区中为项目提供有向无环图 (DAG) 的可视化表示。有关 dbt 项目编译的更多信息，请参阅在 dbt 文档中 编译 (https://docs.getdbt.com/reference/commands/compile)。

在工作区中编译项目后，您可以查看 DAG。您也可以打开 models 文件夹中的任何 SQL 文件，以并排选项卡查看模型 SQL 和编译后的 SQL 模型。

1. 选择要编译的项目和目标。

2. 从命令列表中选择 Compile，然后选择执行按钮（可选，您可以选择向下箭头并指定编译命令实参）。

3. 在工作区编辑器下方的区域中，选择 DAG 选项卡。

   您可以使用 DAG 窗格在 Snowflake 中可视化 dbt 项目从源文件到物化数据模型对象的转换。

   • 在窗格中的任意位置点击并拖动以平移视图。

   • 使用 + 和 -- 按钮放大和缩小。

4. 要在编辑器中查看对象源文件的内容，请为任意对象选择磁贴。

5. 要在工作区编辑器中以分割窗格视图查看编译的 SQL，请执行以下步骤：

   1. 在 DAG 中，选择 dbt SQL 模型文件的磁贴；例如，orders。

      --OR--

      在工作区文件列表中，选择 dbt 项目 models 子目录中的任何文件，以在工作区编辑器中将其打开。

   2. 在工作区编辑器的右上角选择 View Compiled SQL，以分隔窗格视图查看编译后的 SQL。

运行 dbt 开发项目并验证物化的 Snowflake 对象¶

执行 dbt run 命令将使用项目 profiles.yml 文件中指定的 Snowflake 仓库和角色对目标数据库和架构执行编译后的 SQL。在此步骤中，我们将在您的 dbt 演示项目中物化 Dev 目标的输出。然后，在工作区中创建一个名为 dbt_sandbox.sql 的 SQL 工作表，可以在该工作区中运行 SQL 以验证对象的创建情况。

1. 在 Profile 列表中，选择 Dev。

2. 在命令列表中，选择 Run，然后选择执行按钮。

   输出窗格显示运行的完成状态。

3. 在 tasty_bytes_dbt_demo 项目中，导航到 examples 文件夹，选择文件夹名称旁边的 +，然后选择 SQL File。

4. 输入 dbt_sandbox.sql，然后按 Enter。

5. 在 dbt_sandbox.sql 的工作区选项卡中，运行以下查询：

   SHOW TABLES IN DATABASE tasty_bytes_dbt_db;
   

   Copy

   在 Status and Results 窗格中，您应该会看到表 CUSTOMER_LOYALTY_METRICS、ORDERS 和 SALES_METRICS_BY_LOCATION。

6. 要查看您的 dbt 项目运行时创建的视图，请运行以下命令：

   SHOW VIEWS IN DATABASE tasty_bytes_dbt_db;
   

   Copy

将文件更新从工作区推送到存储库¶

现在，您已经更新了工作区并将项目作为 dbt 项目对象进行编译、测试、运行和部署，您可以将您在工作区中所做的更改推送到您的专用 GitHub 存储库。公共存储库不支持此步骤。

1. 打开工作区后，选择 Changes。

   工作区文件列表经过筛选，仅显示自您与 Git 存储库同步以来发生更改的文件。

   • A 表示文件已新增到工作区中，而不是新增到 Git 存储库中。

   • M 表示文件已修改。

   • D 表示文件已删除。

2. 选择一个文件来查看自上次拉取（在本例中为创建工作区时）以来的 GitHub 差异。

3. 在工作区文件列表上方的菜单栏上，验证本教程的分支选择器是否设置为 main。

4. 选择 Push 按钮，然后在提供的框中输入提交消息；例如，使用来自 Snowflake 上的 dbt 的初始更改更新项目。

5. 选择 Push。

   推送到您的存储库可能需要几分钟。

从工作区部署 dbt 项目对象¶

从工作区部署 dbt 项目会创建 dbt 项目对象。您可以使用该对象在工作区之外计划、运行和监控 Snowflake 中的 dbt 项目。

将 dbt 项目对象从工作区部署到 Snowflake 数据库和架构时，您可以创建或覆盖之前创建的对象。

1. 在工作区编辑器的右侧，选择 Connect » Deploy dbt project。

2. 选择 Select database and schema，然后选择 TASTY_BYTES_DBT_DB 数据库和 DEV 架构。

3. 在 Select or Create dbt Object 下，选择 Create dbt Object。

4. 在 Enter Name 下，输入 TASTY_BYTES_DBT_PROJECT，然后选择 Deploy。

   Output 选项卡显示在 Snowflake 上运行的命令，类似于以下示例：

   create or replace DBT PROJECT "TASTY_BYTES_DBT_DB"."DEV"."TASTY_BYTES_DBT_PROJECT" from snow://workspace/USER$MYUSER.PUBLIC."tasty_bytes_dbt_demo"/versions/live/dbt
   
   tasty_bytes_dbt_project successfully created.
   

   Copy

   现在，连接菜单显示您创建的 dbt 项目对象的名称，其中包含以下选项：

   • Redeploy dbt project – 使用 ALTER 项目的当前工作区版本更新 dbt 项目对象。这会使 dbt 项目对象的版本增加一。有关更多信息，请参阅 dbt 项目对象和文件的版本控制。

   • Disconnect – 断开工作区与 dbt 项目对象的连接，但不删除 dbt 项目对象。

   • View project – 在对象资源管理器中打开 dbt 项目对象，可以在其中查看 dbt 项目对象的 CREATE DBT PROJECT 命令和项目的运行历史记录。

   • Create schedule – 为您提供创建按计划运行 dbt 项目对象的任务的选项。有关更多信息，请参阅 创建任务来计划 dbt 项目的执行。

   • View schedules – 打开运行 dbt 项目对象的计划（任务）列表，并可选择在对象资源管理器中查看任务详细信息。

5. 要验证项目的创建情况，请执行以下一项或两项任务：

   • 在 dbt 项目的菜单中，选择 View project，在对象资源管理器中打开 dbt 项目对象。

     --OR--

   • 在您之前创建的 dbt_sandbox.sql 文件工作表中，运行以下命令：

     SHOW DBT PROJECTS LIKE 'tasty%';
     

     Copy

创建任务来计划 dbt 项目的执行¶

现在您已经部署了 dbt 项目对象，您可以使用工作区或 SQL 设置一项任务，在 dbt 项目对象上执行 dbt 命令。

以下步骤将设置一个计划，使 dbt 项目在每小时的第 1 分钟执行一次。该任务使用 --select 选项执行 dbt run 命令，以运行 dbt 项目中的 customer_loyalty_metrics 模型。

1. 在工作区编辑器右上角的 dbt 项目菜单中，选择 Create schedule。

2. 在 Schedule a dbt run 对话框中，执行以下操作：

   • 对于 Schedule name，输入任务的名称；例如，run_prepped_data_dbt。

   • 对于 Frequency，请将所选时区的 Hourly 保持在 01。

   • 在 dbt properties 下：

     • 对于 Operation，选择 run。

     • 对于 Profile，选择 dev。

     • 对于 Additional flags，输入 --select customer_loyalty_metrics。

3. 选择 Create。

   Snowflake 会创建一个任务，该任务使用这些参数运行 EXECUTE DBT PROJECT 命令。有关任务和任务选项的更多信息，请参阅 任务简介 和 CREATE TASK。

4. 在 dbt 项目菜单中，选择 View schedules，然后从列表中选择您的计划。

   对象资源管理器将打开您的数据库，任务 Task Details 窗格已打开。Task Definition 显示类似以下的 CREATE TASK 命令：

   CREATE OR REPLACE TASK tasty_bytes_dbt_db.dev.run_prepped_data_dbt
           WAREHOUSE=tasty_bytes_dbt_wh
           SCHEDULE ='USING CRON 1 * * * * America/Los_Angeles'
         AS
     EXECUTE DBT PROJECT tasty_bytes_dbt_project ARGS='run --select customer_loyalty_metrics --target dev';
   

   Copy

清理¶

在本教程结束后，您可以删除为清理而创建的数据库、工作区和仓库。

在 dbt_sandbox.sql 工作表中运行以下 SQL 命令，以移除您创建的仓库、TASTY_BYTES_DBT_DB 和 TB _101 数据库，以及在数据库中创建的所有架构和对象：

DROP WAREHOUSE IF EXISTS tasty_bytes_dbt_wh;
DROP DATABASE IF EXISTS tasty_bytes_dbt_db;
DROP DATABASE IF EXISTS tb_101;

Copy

要删除您的 tasty_bytes_dbt_demo 工作区：

• 在工作区资源管理器顶部工作区菜单旁边的垂直省略号菜单 中选择 Delete，然后在出现提示时确认删除。