O Elementary

O Elementary pode ser definido como uma ferramenta de Observabilidade para projetos de transformação de dados com o dbt. Entretanto, quando falamos nele é muito importante distinguir dois componentes:

1. **O pacote Elementary do dbt:** um pacote do dbt responsável por:

   1. Coletar logs e artefatos do dbt, com metadados do projeto;
   2. Fazer upload desses dados em tabelas de metadados de um data wharehouse (BigQuery, no caso da BD);
   3. Organizar esse metadados como um schema dbt à parte, que pode ser materializado e configurado;
   4. Adicionar testes e macros para detecção de anomalias.

   <aside> ⚠️

   Sobre artefatos do dbt e como o Elementary faz esse upload, consulte: Esta documentação

   </aside>

2. **Elementary open-source CLI tool (Elementary OSS):** um CLI que trabalha com o pacote Elementary do dbt para produzir:

   1. Relatórios de observabilidade;
   2. Monitoramento e alertas.

   <aside> ⚠️

   Idealmente, as versões precisam ser compatíveis, ou seja, o mesmo número de versão do elementary dbt package precisa ser usado como versão do Elementary CLI.

   </aside>

Elementary + dbt core

O dbt core pode ser integrado ao Elementary (ao pacote e à CLI) desde que a plataforma usada como data wharehouse seja compatível. Logo mais isso ficará mais claro, quando falarmos das versões do Elementary OSS e o adaptador para o wharehouse.

Pré-requisitos

1. Deploy do pacote Elementary no projeto dbt :
   1. Listar o Elementary no packages.yaml no seu diretórtio de projeto do dbt
   2. Rodar o dbt deps

packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1
  - package: elementary-data/elementary
    version: 0.6.10 
    # version: 0.20.0    # -> Mais recente
    # version: 0.14.1    # -> Instalada anteriormente, mas incompatível com o projeto atual

1. Adicionar o elementary ao dbt-project.yaml

   O elementary vai ter seu próprio schema (dataset, para quem usa BigQuery).

   Ver https://docs.getdbt.com/docs/build/custom-schemas

2. Um schema à parte só para o Elementary e seus modelos.

3. Materialização do projeto dbt configurada: não deve haver configurações globais de materialização que possam intervir nas configurações do schema do Elementary, uma vez que alguns modelos precisam ser materializados como incrementais

   models:
     my_project:
       materialized: "{{ 'table' if target.name == 'prod-cloud' else 'view' }}"
   
     elementary:
       +schema: "elementary"
   

4. Um profile para o elementary no profiles.yaml

   Pode ser feito também através do:

   dbt run-operation elementary.generate_elementary_cli_profile
   

   Como deve ser o profile, segundo a documentação do Elementary:

   ## BIGQUERY ##
   ## By default, edr expects the profile name 'elementary'.      ##
   ## Configure the database and schema of elementary models.     ##
   ## Check where 'elementary_test_results' is to find it.        ##
   elementary:
     outputs:
       default:
         type: bigquery
         project: PROJECT_ID
         dataset: elementary
         method: service-account
         keyfile: PATH_TO_CREDENTIALS_FILE.JSON
         threads: 2
         location: [dataset location]
   

   Como está no nosso projeto:

   elementary:
     outputs:
       default:
         type: bigquery
         method: service-account
         keyfile: "{{ env_var('BD_SERVICE_ACCOUNT_DEV', '/credentials-dev/dev.json') }}"
         project: basedosdados-dev      # -> Estamos monitorando o ambiente dev
         dataset: elementary
         location: US                   # -> Importante ter a location
         threads: 2
   

5. Instalar o CLI do elementary

uv add elementary-data==0.6.1        # -> Mesma versão do package no dbt
uv add 'elementary-data[bigquery]'   # -> O Elementary tem compatibilidade com BQ

1. Modelos elementary e Artefatos dbt

Cada execução do dbt gera artefatos com metadados sobre os recursos, configurações e resultados de execução projeto.

pipelines/
    ├── ...
    ├── dbt-packages/
    ├── macros/
    ├── models/
    ├── pipelines/
    ├── target/
    │   ├── compiled/
    │   ├── run/
    │   ├── graph.gpickle
    │   ├── manifest.json        # Artefato
    │   ├── partial_parse.msgpack
    │   └── run_results.json     # Artefato
    └── ...

O elementary tem macros que extraem campos específicos dos artefatos e inserem nas tabelas, nos modelos do pacote. Algumas atualizações acontecem por meio de hooks, quando o dbt é executado (dbt run / test / build), e algumas somente quando os modelos são executados.

Os modelos dividem-se em: