Instantâneo do dbt: Um tutorial completo

O dbt (ferramenta de construção de dados) é uma ferramenta poderosa que os analistas e engenheiros de dados usam pra transformar, testar e documentar dados na pilha de dados moderna. 

Embora seja bem conhecido pelas suas capacidades de modelagem, outro recurso importante é o dbt snapshot, que permite capturar dimensões que mudam lentamente (SCD) no seu data warehouse.

Este tutorial vai te explicar em detalhes o que são os snapshots do dbt, como eles funcionam e como implementá-los. Eu vou:

• Defina o que são instantâneos dbt.
• Explica quando e por que usar instantâneos.
• Faça um instantâneo passo a passo.
• Visualize dados instantâneos.
• Compartilhe algumas das melhores práticas e desafios.

Para saber mais sobre o dbt, não deixe de conferir nosso guia “ ” (O que é o dbt?). Uma introdução prática para engenheiros de dados e nosso curso Introdução ao dbt.

O que são instantâneos do dbt?

Um instantâneo dbt é um jeito de acompanhar as mudanças nos registros ao longo do tempo, principalmente para tabelas onde as mudanças históricas não são mantidas por padrão. Os instantâneos são usados principalmente para implementar Dimensões de Mudança Lenta (SCD) Tipo 2. Eles guardam versões das linhas quando as colunas monitoradas mudam. 

Os casos de uso incluem:

• Acompanhar as mudanças nos perfis dos clientes ao longo do tempo.
• Monitorar as mudanças de status nos dados operacionais.
• Registrando a evolução dos atributos de dimensão para relatórios históricos precisos.

Por que usar instantâneos do dbt? Benefícios e casos de uso

Os instantâneos do dbt são super úteis porque funcionam como um registro das mudanças nos dados ao longo do tempo, permitindo análises históricas e relatórios de conformidade.

Vantagens

Aqui estão alguns benefícios que você vai ter ao usar o Snapshots:

• Análise de tendências: Entenda como o comportamento, os atributos ou os status dos clientes mudam.
• Auditoria e conformidade: Mostrar os dados históricos para os auditores ou reguladores.
• Depuração de pipelines de dados: Identifique quando um registro mudou de repente para ver o que rolou.

Casos de uso comuns

Os instantâneos podem ser úteis em algumas situações específicas, como:

• Acompanhar as atualizações de associações em programas de fidelidade.
• Registrando o histórico de preços dos produtos no varejo.
• Registrando as mudanças de departamento dos funcionários nos sistemas de RH.

Fundamentos da arquitetura

Os instantâneos se integram perfeitamente ao ecossistema do dbt, aproveitando sua configuração e gerenciamento de execução para criar tabelas históricas de forma eficiente.

Vamos dar uma olhada nos tipos de modelos usados nos dados como exemplo.

Existem dois modelos usados para os dados:

• Modelos padrão: Transforme os dados para criar tabelas do estado atual.
• Modelos instantâneos: Crie tabelas com versões pra acompanhar as mudanças históricas.

Esses dois modelos são diferentes em termos de finalidade, métodos de armazenamento e aplicações.

Aqui vai um resumo das diferenças entre eles:

Como funcionam os instantâneos do dbt

Os instantâneos geralmente seguem um fluxo de trabalho estruturado que garante que todas as alterações sejam capturadas de forma sistemática, envolvendo as seguintes etapas:

1. : Defina a estratégia de instantâneo, chaves exclusivas e colunas de detecção de alterações.
2. Execução: Execute “ dbt snapshot ” para comparar os dados atuais com os instantâneos existentes.
3. Armazenamento: o dbt insere novos registros para as alterações detectadas, atualizando os carimbos de data/hora de validade.

Mas como as mudanças são rastreadas no dbt?

Todas as alterações são registradas na tabela Instantâneo de saída.

Se alguma mudança for encontrada, o dbt atualiza o campo “ dbt_valid_to ” da versão anterior com a data e hora atuais e adiciona uma nova linha com o campo “ dbt_valid_from ” com a data e hora atuais.

Estratégias instantâneas no dbt

Os instantâneos usam duas estratégias principais para detectar alterações.

1. Estratégia de carimbo de data/hora

• Definição: Usa um campo de carimbo de data/hora pra detectar alterações.
• Quando usar um: A tabela de origem tem carimbos de data/hora confiáveis updated_at.

2. Verificar estratégia

• Definição: Compare colunas específicas diretamente.
• Quando usar um: A tabela de origem não tem registros de data e hora confiáveis, mas as alterações nos atributos precisam ser rastreadas.

Exclusões definitivas

Alterações nos dados, como exclusões, também podem ser rastreadas, mas não por padrão. Mas tem um jeito de mudar isso pra monitorar essas alterações de exclusão definitiva.

• Problem: Os instantâneos não rastreiam linhas excluídas por padrão.
• Solução: Defina invalidate_hard_deletes=True para marcar as linhas excluídas com um valor dbt_valid_to, mantendo seu último estado.

Aqui vai um exemplo de uma estratégia de verificação sendo implementada, levando em conta exclusões definitivas:

{%
  snapshot customers_snapshot %}

{%
  set config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='check',
    check_cols=['tier'],
    invalidate_hard_deletes=True
  )
%}

SELECT * FROM {{ source('customers') }}

{% endsnapshot %}

Guia de implementação para instantâneos do dbt

Agora que já sabemos como funcionam os Snapshots do dbt, vamos ver como implementá-los. 

1. Conjunto de dados de exemplo para o tutorial do Snapshot

Para praticar instantâneos, vamos criar uma tabela de clientes de exemplo que imita um sistema de associação do mundo real. Isso nos dá alguns dados concretos para testar estratégias comuns de instantâneos.

import csv
from datetime import datetime

# Define the data
customers_data = [
    ["customer_id", "name", "tier", "updated_at"],  # header row
    [1, "Alice Tan", "Silver", "2025-07-01 10:00:00"],
    [2, "Bob Lee", "Gold", "2025-07-01 10:00:00"],
    [3, "Cheryl Lim", "Silver", "2025-07-01 10:00:00"]
]

# Write data to customers.csv
with open("customers.csv", mode="w", newline="", encoding="utf-8") as file:
    writer = csv.writer(file)
    writer.writerows(customers_data)

2. Configurando seu projeto dbt

Antes de implementar instantâneos, é essencial configurar seu projeto dbt corretamente. Isso garante que seu ambiente esteja configurado para gerenciar modelos, instantâneos, testes e documentação de maneira estruturada e escalável.

O que você precisa saber antes de começar

• Certifique-se de que você tem o Python 3.7+ instalado.
• Instale o dbt usando o pip:

pip install dbt

Troca o dbt-postgres pelo adaptador do seu warehouse, tipo dbt-snowflake ou dbt-bigquery, dependendo do seu ambiente.

Instruções passo a passo para a configuração

1. Vá até a pasta dos projetos que você quer.

É aqui que você vai guardar seus projetos de análise ou ELT. Nesse caso, vamos guardar todos os arquivos relacionados nessa pasta do projeto dbt.

cd ~/dbt-snapshot-project

2. Inicialize um novo projeto dbt.

Crie um arquivo de configuração chamado dbt_project.yml:

Coloque isso no seu arquivo de projeto:

name: dbt_snapshots_project
version: '1.0'
profile: austinchia

seeds:
  dbt_snapshots_project:
    +quote_columns: false

3. Teste sua conexão.

dbt debug

Isso deve ser o resultado do comando:

4. Carregue as sementes em um banco de dados local.

Execute o seguinte comando:

dbt seed

Isso deve ser o resultado do comando:

5. Configure as configurações de conexão do seu banco de dados

No arquivo profiles.yml, que geralmente fica em ~/.dbt/profiles.yml.

Aqui tá o que tem no meu arquivo de perfis:

austinchia:
  target: dev
  outputs:
    dev:
      type: sqlite
      threads: 1
      database: ./dbt_snapshots_project.db
      schema: main
      schema_directory: ./schemas
      schemas_and_paths:
        main: ./dbt_snapshots_project.db
      extensions:
        - "C:/sqlean/crypto.dll"

Se você estiver usando um banco de dados banco de dados SQLite como eu, você vai precisar instalar o extensão SQLean também.

6. Ingira seus dados nos modelos de preparação do dbt:

Crie uma nova pasta chamada modelos. Nessa pasta, crie um arquivo chamado stg_customers.sql.

Coloque o seguinte código no arquivo:

SELECT
  *
FROM {{ ref('customers') }}

7. Crie modelos de preparação usando o seguinte comando no dbt.

dbt run --select stg_customers

Isso deve ser o resultado do comando:

3. Configurando o dbt Snapshot

1. Crie um diretório chamado snapshots/.
2. Escreva seu arquivo SQL de instantâneo com a configuração certa.

Neste exemplo, você pode usar o código a seguir para fazer um instantâneo da estratégia de carimbo de data/hora.

{% snapshot customers_snapshot %}

{{
  config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='timestamp',
    updated_at='updated_at'
  )
}}

select * from {{ ref('customers') }}

{% endsnapshot %}

4. Executando o dbt Snapshot

Executar:

dbt snapshot

Nesse comando, o dbt cria a tabela de instantâneos, caso ela não exista. Ele também insere novas linhas para as alterações encontradas.

Isso deve ser o resultado do comando:

5. Verificando tabelas de instantâneos

Agora que você fez o snapshot, deve ter um novo arquivo snapshot.db criado no diretório do seu projeto.

Eu abri isso no VSCode pra ver como é esse arquivo:

Como você pode ver, tem colunas extras, tipo “ dbt_updated_at ” e outras. Isso é super importante pra saber se os dados foram alterados e quando isso rolou.

Para mais guias práticos sobre o dbt, confira nosso guia Camada semântica com dbt.

Exemplo: Acompanhando alterações de dados com instantâneos dbt

Os instantâneos permitem que as equipes registrem todas as alterações feitas em qualquer atributo de uma tabela ao longo do tempo, o que é super útil para garantir a conformidade, depurar e analisar dados.

1. Crie uma tabela de amostra “ customers ” com os campos relevantes. Isso inclui o ID do cliente, nome, e-mail e carimbo de data/hora atualizado para acompanhar quando as alterações ocorrem.

CREATE TABLE customers (
    customer_id INTEGER PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(100),
    updated_at TIMESTAMP
);

2. Insira os dados iniciais para simular um estado de referência.

Use o código a seguir para inserir dados na tabela. Esses dados vão ser usados como os dados originais antes da alteração.

INSERT INTO customers VALUES 
(1, 'Alice Tan', 'alice@example.com', '2025-07-01 10:00:00'),
(2, 'Bob Lee', 'bob.lee@example.com', '2025-07-01 10:00:00');

3. Escreva uma configuração de instantâneo dbt para acompanhar as alterações de e-mail:

{% snapshot customers_email_snapshot %}

{%
  set config(
    target_schema='snapshots',
    unique_key='customer_id',
    strategy='check',
    check_cols=['email'],
    invalidate_hard_deletes=True
  )
%}

SELECT * FROM {{ source('customers') }}

{% endsnapshot %}

4. Execute dbt snapshot para registrar o estado inicial.

dbt snapshot

5. Simule uma atualização de e-mail na tabela de origem.

Depois, vamos atualizar nossa tabela original, mudando as informações de um cliente pra simular uma alteração nos dados.

UPDATE customers
SET email = 'alice.tan@example.com', updated_at = '2025-07-02 09:00:00'
WHERE customer_id = 1;

6. Execute dbt snapshot de novo para ver a mudança.

dbt snapshot

7. Consulte a tabela de instantâneos.

Para ver as diferenças e as alterações feitas nos dados, você vai ter que consultar a tabela de instantâneos. A tabela deve mostrar as duas versões do endereço de e-mail com suas respectivas janelas de validade:

SELECT customer_id, email, dbt_valid_from, dbt_valid_to
FROM snapshots.customers_email_snapshot
ORDER BY customer_id, dbt_valid_from;

Esse processo garante que você mantenha um histórico completo das alterações nas atualizações por e-mail, o que é essencial para auditorias do GDPR, acompanhamento do histórico de contatos ou análises de suporte ao cliente.

Configuração e gerenciamento avançados

Uma gestão eficaz da configuração permite que as equipes escalem implementações de instantâneos em projetos e ambientes de forma integrada.

1. Configuração no nível do projeto e no nível dos recursos

• Configuração no nível do projeto: Use dbt_project.yml para definir configurações padrão de instantâneos, como esquema de destino ou materializações, que vão valer para todos os instantâneos.
• Configuração no nível do recurso: Substitua as configurações em arquivos SQL de instantâneos individuais para requisitos específicos, garantindo flexibilidade.

2. Personalizando campos de metadados

Por padrão, o dbt cria os campos “ dbt_valid_from ” e “ dbt_valid_to ”. Você pode renomear esses arquivos usando as opções de configuração “ valid_from ” e “ valid_to ” se as normas da sua equipe exigirem convenções de nomenclatura diferentes para maior clareza nas ferramentas de BI ou governança de dados.

3. Migrando configurações antigas do Snapshot

As migrações podem causar algumas diferenças se não forem bem feitas. Aqui estão algumas coisas pra ficar de olho quando você estiver migrando suas configurações de instantâneo:

1. Identificar definições de instantâneos antigas usando estilos de bloco de configuração obsoletos.
2. Refaça as configurações para o formato YAML se estiver usando versões modernas do dbt para manter a consistência.
3. Confirmar se tá tudo certo:
• Executar instantâneos em ambientes de teste.
• Dá uma olhada nas saídas antes de desativar os instantâneos antigos.
4. Desativação: Tira os arquivos de instantâneos antigos e dá uma ajustada na documentação.

4. Integrando com outras ferramentas

As alterações nos dados podem ser acompanhadas em conjunto com os instantâneos do dbt. 

Por exemplo:

• Ferramentas de BI (por exemplo, Power BI, Tableau): Crie visualizações temporais que mostram as mudanças nos atributos ao longo do tempo.
• Plataformas de observabilidade (por exemplo, Monte Carlo, Datafold): Fica de olho na atualização dos dados e na integridade histórica.
• Catálogos de dados (por exemplo, Alation, Collibra): Inclua tabelas de histórico de instantâneos como artefatos de linhagem documentados para conformidade.

Melhores práticas para implementação em produção

Implementar instantâneos dbt na produção precisa de um planejamento cuidadoso pra garantir o desempenho, a manutenção e o valor pro negócio.

É melhor seguir estas dicas:

1. Casos de uso ideal e seleção de tabelas

• Priorize tabelas de dimensões com atributos que mudam lentamente, como perfis de clientes, dados mestre de produtos e contratos de fornecedores.
• Evite tabelas transacionais (por exemplo, itens de linha de pedido) com inserções e atualizações de alta frequência, a menos que seja necessário devido a preocupações com o rápido crescimento do armazenamento.

2. Técnicas de otimização de desempenho

Na produção, você vai querer otimizar seus dados para que as alterações possam ser rastreadas de forma eficiente, sem afetar seu produto.

Aqui vão algumas dicas:

• Indexação: Adicione índices nas colunas “ unique_key ” e “validity” para consultas mais rápidas.
• Particionamento: Divida as tabelas de instantâneos por data para otimizar o desempenho da varredura.
• Agrupamento (específico do warehouse): Use chaves de agrupamento (por exemplo, no BigQuery) em campos de alta cardinalidade para melhorar a velocidade das consultas de filtro.

3. Práticas de manutenção e monitoramento

• Agendamento: Execute instantâneos durante os horários de menor movimento para minimizar o impacto nos custos de computação.
• Monitoramento: Configure alertas para falhas de instantâneos no dbt Cloud ou na sua ferramenta de orquestração.
• Verificações de atualização dos dados: Use testes dbt ou ferramentas de observabilidade para ver se os dados do snapshot estão atualizados.
• Análise de armazenamento: Dá uma olhada de vez em quando no tamanho das tabelas de instantâneos e limpa os dados antigos, se o negócio permitir.

4. Erros comuns

Usar um nome de tabela não exclusivo ( unique_key ) faz com que a versão da linha fique errada. Teste sempre a lógica de exclusividade antes de colocar em prática. 

O aumento do tamanho do snapshot também pode acontecer quando armazenar alterações históricas desnecessárias (por exemplo, colunas com atualizações frequentes de carimbos de data/hora) pode aumentar rapidamente os custos de armazenamento.

Desafios comuns e soluções

Usar instantâneos no dbt pode trazer alguns desafios técnicos específicos:

1. Colisões de chaves únicas

Problema: Linhas duplicadas no instantâneo por causa de chaves únicas mal definidas.

Solução:

• Valide a exclusividade usando testes dbt antes de implantar o snapshot.
• Junta vários campos pra garantir que os nomes compostos sejam únicos quando precisar.

2. Desempenho da consulta temporal

Problema: Consultas lentas ao analisar dados históricos.

Solução:

• Use o particionamento e o agrupamento de warehouse de forma eficaz.
• Sempre filtre as consultas por dbt_valid_from ou intervalos de datas para reduzir o volume de dados verificados.

3. Resolução de problemas de erros de execução do Snapshot

Problemas comuns incluem:

• Esquema ou permissões do banco de dados incorretos.
• Alterações no esquema da tabela de origem (por exemplo, colunas excluídas) que quebram as instruções de SELECT de instantâneos.
• Erros de sintaxe nos blocos de configuração do instantâneo.

Soluções:

• Use dbt debug para ver se a conexão e a configuração estão certas.
• Implementar testes de CI no dbt pra detectar erros antes da implantação.
• Dá uma olhada nos logs de execução do dbt pra ver mensagens de erro mais detalhadas.

Conclusão

Os instantâneos do dbt ajudam as equipes de análise a criar conjuntos de dados históricos robustos com o mínimo de trabalho de engenharia, facilitando a análise de conformidade. Se você quiser saber mais sobre dbt, dá uma olhada no nosso curso sobre Introdução à dbt. Para mais informações e guias, dá uma olhada no nosso Introdução ao pacote dbt-utils e Tutorial do dbt.