Tutorial: Introdução aos projetos dbt no Snowflake¶

Introdução¶

Este tutorial orienta você na criação de um espaço de trabalho para dbt Projects on Snowflake conectado a um repositório GitHub, que você bifurca do nosso repositório getting-started-with-dbt-on-snowflake no Snowflake Labs. Em seguida, você usa o espaço de trabalho para atualizar os arquivos do projeto dbt e testar e executar o projeto dbt, que materializa a saída do modelo de dados do projeto dbt nos bancos de dados e esquemas de destino do Snowflake. Você implanta o projeto para criar um objeto de projeto dbt no Snowflake. Por fim, você configura uma tarefa para executar o projeto de acordo com um cronograma definido.

Configuração do ambiente¶

Conclua as seguintes etapas para configurar o ambiente para este tutorial:

1. Bifurcação e clone do repositório de introdução dbt Projects on Snowflake

2. Criação de warehouse para executar ações de espaço de trabalho (opcional)

3. Criação de banco de dados e esquema para integrações e materializações de modelo

4. Criação da integração de API no Snowflake para conexão com GitHub

5. Criação de integração de acesso externo no Snowflake para dependências de 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;

Criação de espaço de trabalho conectado ao repositório Git¶

Nesta etapa, você cria um espaço de trabalho na Snowsight conectado ao repositório GitHub. Para obter mais informações sobre espaços de trabalho, consulte Espaços de trabalho.

1. Faça login no Snowsight.

2. No menu de navegação do lado esquerdo, selecione Projects » Workspaces.

3. Na lista de espaços de trabalho acima da área de arquivos do espaço de trabalho, em Create Workspace, selecione From Git repository. (A lista de espaços de trabalho tem a seleção padrão My Workspace.)

4. Em Repository URL, insira o URL SSH do repositório GitHub bifurcado, por exemplo, https://github.com/my-github-account/getting-started-with-dbt-on-snowflake.git.

5. Para Workspace name, digite um nome. Mais adiante neste tutorial, usaremos tasty_bytes_dbt.

6. Em API integration, selecione o nome da integração de API que você criou, por exemplo, TB_DBT_GIT_API_INTEGRATION.

7. Se o repositório GitHub é público, selecione Public repository e Create.

   Nota

   O Workspaces não oferece suporte à confirmação e ao envio de alterações de um espaço de trabalho para um repositório público.

8. Se o repositório GitHub é privado, e você criou um segredo para a integração de API durante a configuração, faça o seguinte:

   1. Selecione Personal access token.

   2. Em Credentials secret, selecione Select database and schema.

   3. Selecione na lista o banco de dados (por exemplo, TASTY_BYTES_DBT_DB) e o esquema (por exemplo, INTEGRATIONS) em que você armazenou a integração de API.

   4. Selecione Select secret e escolha o segredo na lista, por exemplo, tb_dbt_git_secret.

9. Selecione Create.

   O Snowflake se conecta ao repositório GitHub que você especificou e abre o novo espaço de trabalho. Uma única pasta no espaço de trabalho chamada tasty_bytes_dbt_demo contém o projeto dbt com o qual você trabalhará.

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

Execução de comandos SQL em tasty_bytes_setup.sql para configurar os dados de origem¶

Como dados de origem para as transformações, o projeto dbt no repositório usa o modelo de dados fundamental para a marca fictícia de food truck Tasty Bytes. O script SQL para criar o modelo de dados está no espaço de trabalho.

1. No espaço de trabalho, navegue até o arquivo tasty_bytes_dbt_demo/setup/tasty_bytes_setup.sql e abra-o.

2. No seletor de contexto no canto superior direito do editor do espaço de trabalho, selecione o warehouse que você criou, por exemplo, TASTY_BYTES_DBT_WH.

3. O arquivo SQL contém os comandos que você já executou neste tutorial. Próximo ao início do arquivo, encontre os seguintes comandos e comente-os para que você não os execute novamente e crie recursos duplicados:

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

   Copy

4. Execute os comandos SQL sem comentários no arquivo.

   Dica

   Use cmd + Shift + Enter para executar todos os comandos sem comentários.

   A guia Output exibe a seguinte mensagem:

   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';

Execução do comando deps do dbt para seu projeto¶

Você pode usar o espaço de trabalho para executar comandos do dbt comuns para um projeto. Para obter uma lista de comandos disponíveis, consulte Comandos do dbt permitidos. Para executar um comando, selecione o Project, o Profile e o comando do dbt nas listas acima do editor do espaço de trabalho. Em seguida, selecione o botão de execução. Use a seta para baixo ao lado do botão de execução para especificar argumentos adicionais que o comando do dbt aceita.

Quando você executa um comando do dbt no espaço de trabalho, a guia Output mostra o comando que é executado no Snowflake (em verde) e o stdout para esse comando, de modo que você possa monitorar o sucesso ou a falha do comando.

O primeiro comando que você deve executar para um projeto dbt é deps, que atualiza as dependências especificadas no arquivo packages.yml do projeto. Haverá falha em outros comandos, a menos que você atualize as dependências. Para obter mais informações, consulte Dependências do dbt.

1. Abaixo do editor do espaço de trabalho, abra a guia Output para que você possa ver o stdout depois de executar os comandos do dbt no espaço de trabalho.

2. Na barra de menus acima do editor do espaço de trabalho, confirme se o Project padrão (tasty_bytes_dbt_demo) está selecionado. Você pode ter qualquer Profile selecionado. Este projeto tem os perfis dev e prod definido no arquivo profiles.yml.

3. Selecione a lista Profile e escolha Enable secondary roles para habilitar as funções secundárias para este projeto e esta sessão.

   Nota

   Você deve habilitar as funções secundárias inicialmente para executar comandos do dbt para cada projeto durante cada sessão do Snowsight. As contas Enterprise Edition podem ser configuradas para proibir funções secundárias para um usuário específico ou todos os usuários. Para obter mais informações, consulte Funções secundárias são necessárias por projeto e sessão.

4. Na lista de comandos, selecione Deps.

5. Ao lado do botão de execução, selecione a seta para baixo.

6. Na janela Deps do dbt, deixe Run with defaults selecionado e, em seguida, digite o nome da External Access Integration que você criou durante a configuração no espaço fornecido, por exemplo, dbt_ext_access.

7. Para executar o comando, selecione Deps.

   A guia Output exibe o comando SQL que é executado no Snowflake, muito semelhante ao seguinte:

   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

   Quando o comando é concluído, aparecem mensagens do stdout semelhantes às seguintes:

   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
   

   O arquivo package_lock.yml é criado e aparece em sua lista de arquivos do espaço de trabalho com um A ao lado. Isso indica que o arquivo foi adicionado ao projeto dbt no espaço de trabalho, com um conteúdo semelhante ao seguinte exemplo:

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

   Copy

Compilação do projeto dbt, visualização do DAG e do SQL compilado¶

A compilação de um projeto no dbt cria o SQL executável dos arquivos SQL modelados e uma representação visual do gráfico acíclico direcionado (Directed Acyclic Graph, DAG) para o projeto no espaço de trabalho. Para obter mais informações sobre a compilação de projetos dbt, consulte compile na documentação do dbt.

Depois de compilar o projeto no espaço de trabalho, você poderá visualizar o DAG. Você também pode abrir qualquer arquivo SQL na pasta models para ver o modelo SQL e o SQL compilado em guias lado a lado.

1. Selecione o projeto e o destino que você quer compilar.

2. Na lista de comandos, selecione Compile e o botão de execução (se preferir, selecione a seta para baixo e especifique os argumentos do comando compile).

3. Na área abaixo do editor do espaço de trabalho, selecione a guia DAG.

   Você pode usar o painel do DAG para visualizar as transformações do projeto dbt de arquivos de origem em objetos de modelo de dados materializados no Snowflake.

   • Clique e arraste a exibição para qualquer lugar no painel para deslocá-la.

   • Use os botões + e – para aumentar e diminuir o zoom.

4. Para visualizar o conteúdo do arquivo de origem de um objeto no editor, selecione o bloco de qualquer objeto.

5. Para ver o SQL compilado em uma exibição de painel dividido no editor do espaço de trabalho:

   1. No DAG, selecione o bloco de um arquivo de modelo SQL do dbt, por exemplo, orders.

      –OR–

      Na listagem de arquivos do espaço de trabalho, selecione qualquer arquivo no subdiretório models do projeto dbt para abri-lo no editor do espaço de trabalho.

   2. Escolha View Compiled SQL no canto superior direito do editor do espaço de trabalho para ver o SQL compilado em uma exibição de painel dividido.

Execução do projeto dbt dev e verificação dos objetos Snowflake materializados¶

O comando run do dbt executa o SQL compilado no banco de dados e esquema de destino usando o warehouse do Snowflake e a função especificados no arquivo profiles.yml do projeto. Nesta etapa, vamos materializar a saída do destino Dev em seu projeto de demonstração dbt. Você cria uma planilha SQL chamada dbt_sandbox.sql no espaço de trabalho, em que você pode executar o SQL para verificar a criação do objeto.

1. Na lista Profile, selecione Dev.

2. Na lista de comandos, selecione Run e o botão de execução.

   O painel de saída mostra o status de conclusão da execução.

3. No projeto tasty_bytes_dbt_demo, navegue até a pasta examples, selecione + ao lado do nome da pasta e selecione SQL File.

4. Insira dbt_sandbox.sql e pressione Enter.

5. Na guia do espaço de trabalho para dbt_sandbox.sql, execute a seguinte consulta:

   SHOW TABLES IN DATABASE tasty_bytes_dbt_db;
   

   Copy

   No painel Status and Results, você deve ver as tabelas CUSTOMER_LOYALTY_METRICS, ORDERS e SALES_METRICS_BY_LOCATION.

6. Para mostrar as exibições que a execução do projeto dbt criou, execute o seguinte comando:

   SHOW VIEWS IN DATABASE tasty_bytes_dbt_db;
   

   Copy

Envio de atualizações de arquivos do espaço de trabalho para seu repositório¶

Agora que você atualizou o espaço de trabalho e compilou, testou, executou e implantou o projeto como um objeto de projeto dbt, pode enviar as alterações feitas no espaço de trabalho para seu repositório GitHub privado. Esta etapa não é permitida para repositórios públicos.

1. Com o espaço de trabalho aberto, selecione Changes.

   A listagem de arquivos do espaço de trabalho é filtrada para mostrar apenas os arquivos alterados desde a sincronização com o repositório Git.

   • A indica um arquivo adicionado ao espaço de trabalho, e não ao repositório Git.

   • M indica um arquivo modificado.

   • D indica um arquivo excluído.

2. Selecione um arquivo para ver a diferença com o GitHub desde o último envio (neste caso, quando o espaço de trabalho foi criado).

3. Na barra de menus acima da listagem de arquivos do espaço de trabalho, verifique se o seletor de ramificação está definido como main para este tutorial.

4. Selecione o botão Push e digite uma mensagem de confirmação na caixa fornecida, por exemplo, Atualizando o projeto com alterações iniciais do dbt no Snowflake.

5. Selecione Push.

   Um envio para seu repositório pode levar vários minutos.

Implantação do objeto de projeto dbt do espaço de trabalho¶

A implantação do projeto dbt de um espaço de trabalho cria um objeto de projeto dbt. Você pode usar o objeto para agendar, executar e monitorar um projeto dbt no Snowflake fora do espaço de trabalho.

Ao implantar o objeto de projeto dbt do espaço de trabalho em um banco de dados e esquema Snowflake, você pode criar ou substituir um objeto que já foi criado.

1. No lado direito do editor do espaço de trabalho, selecione Connect » Deploy dbt project.

2. Selecione Select database and schema e escolha o banco de dados TASTY_BYTES_DBT_DB e o esquema DEV.

3. Em Select or Create dbt Object, selecione Create dbt Object.

4. Em Enter Name, digite TASTY_BYTES_DBT_PROJECT e selecione Deploy.

   A guia Output exibe o comando que é executado no Snowflake, muito semelhante ao seguinte exemplo:

   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

   O menu Connect agora exibe o nome do objeto de projeto dbt que você criou, com as seguintes opções:

   • Redeploy dbt project: atualiza o objeto de projeto dbt com a versão atual do espaço de trabalho do projeto usando ALTER. Isso incrementa a versão do objeto de projeto dbt em um. Para obter mais informações, consulte Controle de versão para objetos e arquivos de projeto dbt.

   • Disconnect: desconecta o espaço de trabalho do objeto de projeto dbt, mas não exclui o objeto.

   • View project: abre o objeto de projeto dbt no explorador de objetos, em que é possível visualizar o comando CREATE DBT PROJECT para o objeto de projeto dbt e o histórico de execuções do projeto.

   • Create schedule: mostra opções para você criar uma tarefa que executa o objeto de projeto dbt de acordo com um cronograma. Para obter mais informações, consulte Criação de tarefa para agendar a execução do projeto dbt.

   • View schedules: abre uma lista de cronogramas (tarefas) que executam o objeto de projeto dbt, com a opção de visualizar os detalhes das tarefas no explorador de objetos.

5. Para verificar a criação do projeto, execute uma ou ambas as tarefas abaixo:

   • No menu do projeto dbt, selecione View project para abrir o objeto de projeto dbt no explorador de objetos.

     –OR–

   • Na planilha do arquivo dbt_sandbox.sql que você criou, execute o seguinte comando:

     SHOW DBT PROJECTS LIKE 'tasty%';
     

     Copy

Criação de tarefa para agendar a execução do projeto dbt¶

Agora que você implantou o objeto de projeto dbt, pode usar o espaço de trabalho ou o SQL para configurar uma tarefa que executa um comando do dbt em seu objeto de projeto dbt.

As etapas a seguir configuram um cronograma para executar o projeto dbt a cada hora, um minuto após a hora. A tarefa executa o comando run do dbt com a opção --select para executar o modelo customer_loyalty_metrics no projeto dbt.

1. No menu do projeto dbt no canto superior direito do editor do espaço de trabalho, escolha Create schedule.

2. Na caixa de diálogo Schedule a dbt run, faça o seguinte:

   • Em Schedule name, insira um nome para a tarefa, por exemplo, run_preped_data_dbt.

   • Em Frequency, mantenha Hourly como 01 para o fuso horário selecionado.

   • Em dbt properties:

     • Para Operation, selecione run.

     • Para Profile, selecione dev.

     • Em Additional flags, insira --select customer_loyalty_metrics.

3. Escolha Create.

   O Snowflake cria uma tarefa que executa o comando EXECUTE DBT PROJECT usando esses parâmetros. Para obter mais informações sobre tarefas e opções de tarefas, consulte Introdução às tarefas e CREATE TASK.

4. No menu do projeto dbt, selecione :ui:`View schedules`e escolha o cronograma na lista.

   O explorador de objetos é aberto para seu banco de dados com o painel Task Details aberto para a tarefa. A Task Definition mostra um comando CREATE TASK similar a este:

   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

Limpeza¶

Você poderá excluir os bancos de dados, os espaços de trabalho e o warehouse criados para limpeza após este tutorial.

Execute os seguintes comandos SQL da planilha dbt_sandbox.sql para remover o warehouse, os bancos de dados TASTY_BYTES_DBT_DB e TB_101 que você criou e todos os esquemas e objetos criados nos bancos de dados:

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

Copy

Para excluir o espaço de trabalho tasty_bytes_dbt_demo:

• No menu de três pontos verticais ao lado do menu do espaço de trabalho na parte superior do explorador de espaços de trabalho, selecione Delete e confirme a exclusão quando for solicitado.