Guia prático do DBT: Desvendando a arquitetura e configuração inicial.

Uma jornada em 3 etapas para dominar a ferramenta de transformação de dados — DBT — Parte 1 de 3.

Este será o primeiro de uma série de artigos que têm como objetivo guiar e explicar mais sobre o DBT, uma ferramenta de transformação de dados amplamente utilizada no mercado atual. O propósito deste artigo é introduzir a ferramenta, fornecer uma visão das motivações e da arquitetura implementadas na Pebmed, uma empresa do grupo Afya, e apresentar um passo a passo para começar a utilizar a ferramenta localmente.

>> Mas afinal, o que é o DBT?

O DBT, ou Data Build Tool, é uma ferramenta de transformação de dados que se concentra em consultas SQL, permitindo que engenheiros e analistas de dados manipulem seu Data Warehouse com mais eficiência.

Abaixo, podemos visualizar o fluxo de transformação na ferramenta. O DBT possui integração nativa com as principais plataformas de Data Warehouse em nuvem. Ao ler os dados brutos desses provedores, podemos passar pelas seguintes etapas:

1. Desenvolvimento: Aqui, é possível escrever código de transformação em arquivos .sql e .py. É importante ressaltar que a disponibilidade do código Python pode variar entre as plataformas, sendo necessário consultar o site oficial para confirmar.
2. Teste e documentação: É possível realizar testes locais em todos os modelos antes de enviá-los para o repositório de produção. Além disso, é possível documentar tudo o que for criado, como tabelas e colunas, adicionar informações personalizadas e visualizar a linhagem dos modelos. Isso permite entender rapidamente as dependências e realizar análises de impacto para possíveis alterações.
3. Deploy: É possível realizar um deploy seguro no ambiente de desenvolvimento. O controle de versão habilitado pelo Git permite colaboração múltipla sem causar grandes danos ao ambiente de produção final.

>> Implementando a ferramenta na Afya

A ferramenta já estava sendo utilizada inicialmente em uma das empresas adquiridas pelo grupo desde 2020, a iClinic, e em 2022 fizemos a implementação nos outros pilares. Neste artigo, vou me concentrar no processo realizado na BU Pebmed.

O projeto de implementação do DBT teve como objetivo:

• Dar autonomia aos chapters de análise e ciência de dados para realizar transformações nos dados de negócio por meio de consultas SQL.
• Criar um ambiente que sirva como fonte única da verdade, com métricas, insights e definições de negócio bem organizados e documentados.
• Disponibilizar recursos para definição de testes, análise de impacto por meio da linhagem das tabelas e criação de alertas para identificar problemas.
• Oferecer liberdade à equipe de engenharia em relação à plataforma de orquestração, substituindo o Snowplow BDP pelo DBT Cloud.

Arquitetura

Atualmente, existem duas versões do DBT:

• DBT Core: É uma ferramenta de linha de comando open source que permite a transformação de dados localmente seguindo as melhores praticas.
• DBT Cloud: É uma interface web que permite a implementação rápida e confiável do DBT. É possível desenvolver, testar, agendar e visualizar modelos por meio dessa interface.

Na Afya, optamos por trabalhar localmente com o desenvolvimento e teste do nosso ambiente. Com o suporte de uma imagem Ubuntu, realizamos os processos de configuração de um contêiner Docker igual para todos os usuários. Um contêiner é uma unidade isolada que empacota uma aplicação juntamente com todas as suas dependências, permitindo sua execução consistente e portátil em diferentes ambientes. Com isso, conseguimos adaptar e isolar um ambiente exclusivo para o desenvolvimento local.

Seguimos o fluxo demonstrado na imagem abaixo, onde os usuários podem colaborar com nosso repositório de produção no GitLab, que é executado diariamente com a ajuda do DBT Cloud como orquestrador. Como nossa arquitetura é projetada na AWS, optamos por continuar utilizando o Redshift como nossa ferramenta de Data Warehouse. Dessa forma, o DBT Cloud lê as modelagens no repositório e as divide em etapas de execução para gerar os dados já tratados e atualizados no DW. Esses dados são posteriormente utilizados nos dashboards apresentados às áreas de negócio por meio do Power BI, que realiza uma conexão ODBC com o Redshift.

>> Configurando o computador

O processo de configuração do seu computador será dividido em duas partes: primeiro, configuraremos o Docker e, em seguida, o VSCode.

Docker

O Docker é uma plataforma de virtualização que permite criar e executar aplicativos em contêineres isolados, fornecendo um ambiente seguro e personalizável para o desenvolvimento dos modelos dbt. Para configura-lo siga os passos abaixo:

1. Primeiro, vamos instalar a ferramenta. Você pode encontrar o instalador neste [link]. Se você estiver usando o Windows, o Docker pode solicitar a instalação do WSL.

2. Em seguida, escolha uma pasta de sua preferência, de preferência dentro do seu diretório de usuário, e crie uma pasta chamada “dbt-config” com os seguintes arquivos listados abaixo:

2.1. dbt-config > Dockerfile

FROM ubuntu:20.04
COPY ./.dbt /root/.dbt

RUN apt update && apt upgrade -y
RUN apt install telnet -y
RUN apt install vim -y
RUN apt install git -y
RUN apt install python3 -y
RUN apt install python3-pip -y
RUN pip install dbt-core==1.2.2 dbt-redshift==1.2.1

Esse arquivo será responsável pela configuração do nosso contêiner. Há dois pontos de atenção na última linha:

• A versão do dbt-core é constantemente atualizada, é importante acompanhar as páginas oficiais do dbt para ficar por dentro das atualizações. No entanto, tome cuidado com as mudanças de versão para evitar conflitos, especialmente se você estiver usando o DBT Cloud como seu orquestrador. O ideal é manter ambos na mesma versão.
• A questão da versão também se aplica ao adaptador escolhido. No nosso caso, como trabalhamos com o Redshift, fazemos a instalação correspondente a ele. Certifique-se de utilizar o adaptador referente ao Data Warehouse definido pela sua empresa nessa parte.

2.2- dbt-config > .dbt > profiles.yml

Ao invocar o dbt por linha de comando para executar modelos e processos, ele faz a leitura do seu profile para estabelecer a conexão com o banco de dados e identificar algumas personalizações de ambiente.

Antes de prosseguir para as próximas etapas, você deverá criar o arquivo profiles.yml e preencher as informações com os seus dados. Abaixo está um exemplo utilizado aqui na Afya:

config:
  partial_parse: false

pebmed: 
 target: dev 
 outputs: 
   dev: 
       type: redshift 
       host: localhost
       user: seu_usuario_dw
       pass: sua_senha_dw
       port: 5439 
       dbname: nome_database
       schema: dbt_eng 
       threads: 4 
   prod: 
       type: redshift 
       host: host_dw
       user: seu_usuario_dw
       pass: sua_senha_dw
       port: 5439
       dbname: nome_database
       schema: dbt_prod 
       threads: 4

Você pode ter quantos profiles forem necessários, sendo 1 profile por Data Warehouse. No entanto, normalmente as empresas trabalham com um único DW. Vamos explicar os principais tópicos separadamente:

• Profile name: Substitua pelo nome do seu projeto dbt. Geralmente, é utilizado o nome da empresa como referência. Aqui, utilizamos “pebmed”. O nome do profile deve ser o mesmo que consta no arquivo “dbt_project.yml”, que é o documento com as configurações principais do seu projeto.
• Target: Você pode criar mais de um target, mas neste campo inicial, você deve definir qual será o padrão. Sempre que você executar um modelo e não especificar um target específico, será utilizado o padrão definido aqui. Aqui, utilizamos “dev” como padrão.
• Outputs: Aqui, faremos a separação por target. Na Afya, utilizamos o target “dev” para todos os usuários, nos permitindo incluir algumas restrições no ambiente. Além disso, para a equipe de engenharia que precisa realizar manutenções constantes em produção, também incluímos um target “prod”.
  - Type: O tipo de Data Warehouse ao qual você está conectando.
  - Credenciais: Nesta parte, você deve incluir as credenciais do seu Data Warehouse, como host local, usuário, senha, porta e nome do banco de dados.
  - Schema: O prefixo do schema no qual o dbt irá gerar os objetos. Aqui, utilizamos 3: “dbt_prod” para o ambiente de produção, “dbt_analise” para o ambiente de teste da equipe de ciência e análise, e “dbt_eng” para o ambiente de teste da equipe de engenharia.
  - Threads: A quantidade máxima de modelos que o DBT poderá executar simultaneamente, o padrão é 4 mas você pode personalizar nesse campo.

OBS: Em máquinas Mac, os arquivos que começam com “.” geralmente ficam ocultos. Para visualizá-los, pode ser necessário usar os comandos: Cmd + Shift + “.”.

3. Se você estiver usando um computador com Windows, abra o “Windows PowerShell”. Se estiver usando um Mac, abra o Terminal.

4. Com o aplicativo aberto, navegue até a pasta onde você salvou o arquivo “dbt-config”. Para isso, você pode voltar uma pasta usando o comando “cd ..” ou avançar para uma pasta usando o comando “cd nome_da_pasta”.

5. Uma vez dentro da pasta “dbt-config”, execute o seguinte comando. Isso iniciará uma série de instalações. Aguarde até que todas as etapas sejam concluídas.

docker build -t ubuntu:20.04 .

6. Agora execute o seguinte comando. Ele criará um novo contêiner com a imagem do Ubuntu e você entrará diretamente nele devido ao comando “-it”.

docker run -it --name dbt_pebmed ubuntu:20.04

OBS: Você pode escolher um nome de sua preferência para o contêiner. Aqui, usamos o padrão “dbt_” + nome_da_empresa.

7. Execute o comando “cd root”.

8. A partir deste ponto, teremos dois caminhos diferentes. Se você ainda não tiver um projeto criado no dbt, crie uma pasta com o nome escolhido usando o comando “mkdir nome_do_projeto” (na Afya, usamos o nome “dbt-dev”) e siga para a configuração do seu VSCode. Mais detalhes sobre quais pastas criar e a função de cada uma delas serão explicados na parte 2 deste guia.

Se você já tiver um projeto dbt criado em um repositório online, faça o clone dele localmente. Para isso, acesse o seu repositório, vá para a opção de clone e copie o link HTTPS. Em seguida, execute o seguinte comando:

git clone link_https

OBS: Ele solicitará seu nome de usuário (e-mail) e senha (token). Caso ainda não tenha criado um token, no caso do Gitlab, vá em “edit profile > access tokens” e crie um token com as permissões “read_repository” e “write_repository” habilitadas.

Uma dica importante é que, ao incluir sua senha no terminal, você não verá nada acontecendo, mas a senha estará lá ocultada. Basta colar ou digitar a senha uma vez e pressionar Enter para que o comando de clone seja executado normalmente.

9. Com o repositório clonado, acesse a pasta de destino usando o comando “cd nome_da_pasta”.

10. Se você tiver pacotes instalados no projeto, instale-os executando o comando “dbt deps”.

Agora seu contêiner Ubuntu está configurado e pronto para uso, já pode fechar o terminal. Na próxima parte, forneceremos algumas dicas sobre como configurar o VSCode para facilitar e personalizar o uso da ferramenta no seu dia a dia.

VSCode

O Visual Studio Code (VSCode) é um editor de código-fonte flexível e altamente personalizável, que é amplamente utilizado no desenvolvimento de software e vai nos facilitar durante a criação e leitura de modelos no DBT. Para configura-lo siga os passos abaixo:

1. Primeiro, instale a ferramenta através deste [link].

2. Abra a ferramenta e instale as seguintes extensões:

OBS: Se você estiver usando um Mac, não é necessário instalar a extensão WSL.

3. Após a instalação das extensões, conecte-se ao contêiner: Clique no ícone do Docker > Botão direito no contêiner selecionado > Attach Visual Studio Code

OBS: Isso abrirá uma nova aba no Visual Studio Code.

4. Agora, abra um novo terminal dentro do VSCode e execute os seguintes comandos em duas partes:

• Parte 1:

code --install-extension bastienboutonnet.vscode-dbt && 
code --install-extension donjayamanne.githistory && 
code --install-extension dorzey.vscode-dbt-language && 
code --install-extension eamodio.gitlens && 
code --install-extension foldager.dbt-shortcuts

• Parte 2 :

code --install-extension innoverio.vscode-dbt-power-user && 
code --install-extension samuelcolvin.jinjahtml && 
code --install-extension mhutchie.git-graph && 
code --install-extension PKief.material-icon-theme

5. Após a instalação das extensões, siga as etapas abaixo:

• Pressione os botões: Ctrl + Shift + P
• Isso abrirá uma barra de busca no topo do VSCode. Procure pela opção: “Preferences: Open User Settings (JSON)”
• Será aberta uma nova aba chamada “settings.json”. Cole o código abaixo:

{ 
    "workbench.iconTheme": "material-icon-theme", 
    "workbench.colorTheme": "Bluloco Dark", 
    "editor.minimap.enabled": false, 
    "launch": { 

        "configurations": [], 
        "compounds": [] 
    }, "files.associations": { 
        "*.sql": "jinja-sql" 
    }, 
    "editor.rulers": [ 
    110 
    ], 
    "editor.tabSize": 2 
}

OBS: Nos tópicos de “icon” e “color”, você pode definir sua preferência, pois algumas pessoas preferem um fundo preto e outras preferem um fundo branco.

6. Se você deseja manter em foco o seu projeto para que, ao abrir o VSCode, vá diretamente para ele, vá em “File > Open Folder” e selecione a pasta do seu projeto, seja a nova pasta ou a pasta clonada. Exemplo: /root/dbt-dev

No dia a dia

Com as configurações finalizadas, para trabalhar com a ferramenta basta abrir o VSCode, iniciar o container através do ícone do Docker e realizar o attach.

É recomendado fechar o ambiente sempre que não estiver em uso, para isso feche a aba extra, siga o mesmo caminho mencionado acima para acessar o container e, em seguida, clique com o botão direito para realizar o stop. Além de liberar espaço de processamento em sua máquina, isso ajuda a evitar que problemas inesperados no computador afetem o andamento do seu projeto.

OBS: Alguns VSCodes já iniciam diretamente na aba do container, nesse caso você pode dar o start e stop diretamente na ferramenta Docker na aba Containers.

A primeira parte deste artigo teve como objetivo fornecer uma visão geral das possibilidades de uso da ferramenta, realizar uma introdução inicial, demonstrar como a adaptamos à nossa arquitetura atual e auxiliar na configuração inicial do ambiente. Nos próximos passos, exploraremos as pastas e arquivos importantes para o funcionamento do ambiente, além de apresentar o DBT Cloud, o orquestrador do nosso projeto.

Espero que este guia seja útil para aqueles que têm interesse em uma solução governada de transformação de dados ou para aqueles que desejam aprimorar seus conhecimentos nesta ferramenta. O DBT é uma ferramenta incrível que transformou a interação diária entre nossa equipe de dados e trouxe maior governança aos conjuntos de dados criados. Se tiver alguma dúvida ou sugestão, não hesite em entrar em contato comigo pelo Linkedin.

English version: https://medium.com/@alice_thomaz/4b8390281272

Parte 2: Organizando as pastas do projeto.