Data Validation

O objetivo desta documentação é apresentar o processo de validação de dados da Carol.

O objetivo do recurso de validação de dados é permitir que dados de tenants sejam validados conforme regras de validação definidas pelo time desenvolvedor de um Carol App. Assim, facilitando as respostas de perguntas como:

• O campo id está preenchido em todos os registros da tabela XPTO?

• O campo value está preenchido e tem apenas valores positivos em todos os registros da tabela ABC?

• A combinação de campos id, client e company é única para cada registro da tabela XYZ ou há repetições?

• Os valores presentes no campo deviceid da tabela clockinrecords são válidos quando comparamos os valores do mesmo campo na tabela devices?

Dentre muitas outras possibilidades.

Modelo da solução

A seguir, é apresentado o modelo implementado da solução:

Nesse diagrama, destacamos o seguinte:

• O time Carol irá disponibilizar uma imagem que executa (dentre outros scripts de integração) o dbt-bigquery versão 1.7.2.
• Toda a validação de dados será feita utilizando o dbt, a imagem disponibilizada contém apenas scripts para que a integração entre plataforma Carol e dbt seja possível.
• Esta imagem disponibilizada será utilizada as-is nos Carol Apps a partir de um Dockerfile, este apenas adicionando os testes que o time de desenvolvimento definir necessários ou outros comandos a serem executados em tempo de build da imagem.

Utilizando o dbt

Importante

Para utilização do recurso, é fundamental que o usuário conheça padrões, linguagem, estrutura de pastas e formas de implementação do dbt. Isso por conta da validação de dados ser feita pelo dbt-bigquery, ferramenta gratuita não pertencente à plataforma Carol. Para mais detalhes, documentações sobre como utilizar o dbt, consulte sua documentação.

Utilizando imagem provida pela plataforma Carol

A plataforma Carol desenvolveu uma imagem personalizada que permite que sejam executados os testes no formato dbt dentro de suas tenants e os resultados sejam disponibilizados na plataforma. A imagem é criada de forma personalizada, que irá esperar que todos os componentes do dbt (tests, models, packages, etc) estejam na pasta /usr/dbt após o build da imagem do seu Carol App. Dessa forma, ao criar o Dockerfile que o seu Carol App utilizará para validar os dados é necessário que estes componentes sejam copiados de forma correta, montando assim a pasta conforme o dbt necessita para executar suas ações. Segue um exemplo abaixo:

FROM gcr.io/labs-ai-apps-production/caroldatavalidation/datavalidation:1.0.0

COPY ./models /usr/dbt/models

COPY ./tests /usr/dbt/tests

Este Dockerfile irá utilizar a imagem personalizada provida pela plataforma Carol e antes da execução da mesma irá copiar o conteúdo da pasta ./models/* para /usr/dbt/models e o conteúdo da pasta ./tests/* para /usr/dbt/tests. Realizando essa cópia, a imagem personalizada irá executar seu entrypoint contendo, entre outros, o comando:

dbt test --profiles-dir /usr/dbt --no-use-colors >> test.txt

Com isso, o dbt será acionado e irá executar conforme estrutura copiada para a pasta /usr/dbt.

Importante

O arquivo profiles.yml será criado dinâmicamente de acordo com a tenant que está executando a task de validação de dados. Dessa forma, não é necessário copiar o arquivo em seu Dockerfile.

Dependências

Por padrão, a imagem personalizada provida pela plataforma Carol instala os pacotes abaixo:

packages:
- package: dbt-labs/dbt_utils
  version: 1.1.1
- package: calogica/dbt_expectations
  version: 0.9.0

Estes pacotes podem ser utilizados livremente pelos usuários sem nenhuma importação adicional. Caso o usuário necessite de versões mais atualizadas destes pacotes ou deseje instalar novos pacotes, basta adicionar o comando abaixo em seu Dockerfile, assim executando em tempo de build a instalação do pacote.

COPY ./packages.yml /usr/dbt

RUN dbt deps >> deps.txt

• O arquivo packages.yml deve estar no formato esperado pelo dbt e copiado para a pasta /usr/dbt.
• Apontando o retorno do comando dbt deps para um arquivo de nome deps.txt fará com que a imagem também envie para o Storage do Carol App o arquivo, assim sendo possível verificar o andamento da instalação de novos pacotes.

Configurando o Data Validation

Agora, vamos verificar como configurar o Data Validation no seu Carol App.

O primeiro passo é possuir um repositório em alguma plataforma de hospedagem de código-fonte como gitHub ou Azure DevOps. O repositório utilizado pode ser o mesmo repositório que contém as pipelines SQL do Carol App, não sendo requisito para a implementação do recurso. Abaixo temos uma sugestão de como organizar o repositório para facilitar a implementação do Data Validation.

A imagem acima demonstra um repositório para o Carol App MyCarolApp, suas pipelines SQL e uma pasta chamada data-validation. Dentro dela ficarão o Dockerfile do processo que criará a sua imagem específica com arquivos de validação próprios para seu Carol App e ao final executará a imagem provida pela plataforma Carol, que integrará a validação de dados dbt com a plataforma, facilitando o fluxo de validação de dados dentro de tenants.

Manifesto utilizando a imagem

Como estamos utilizando uma imagem e um container, o recurso de validação de dados estará presente como um AI Process, dentro do seu Carol App. Dessa forma será necessário adicionar ao manifesto de Carol App (manifest.json) o código abaixo:

{
    "batch": {
        "processes": [{
            "name": "Data_Validation",
            "algorithmName": "datavalidation",
            "algorithmDescription": {
                "en-US": "Your Description.",
                "pt-BR": "Sua Descricao"
            },
            "algorithmTitle": {
                "en-US": "Data Validation",
                "pt-BR": "Data Validation"
            },
            "instanceProperties": {
                "profile": "",
                "properties": {
                    "dockerName": "datavalidation",
                    "instanceType": "c1.nano"
                },
                "preemptible": false,
                "environments": {
                    "PREFECT_LOGGING_HANDLERS_CONSOLE_FORMATTER": "json"
                }
            }
        }]
    },
    "docker": [
    {
        "dockerName": "datavalidation",
        "dockerTag": "0.0.1",
        "gitBranch": "main",
        "gitPath": "/data-validation",
        "instanceType": "c1.nano",
        "gitDockerfileName": "Dockerfile",
        "gitRepoUrl": "https://url.com/seurepositorio"
    }]
}

Caso o seu Carol App já possua outros AI Process, basta adicionar os trechos acima ao seu manifesto de Carol App já existente. Após a adição do código ao manifesto de Carol App, será necessário reenviar o manifesto por meio do menu Files do seu Carol App, dentro da tenant que o desenvolve. Após o reenvio, o Ai Process de validação de dados deve aparecer no Carol App similar à imagem abaixo.

Consultando os resultados da validação de dados

Após a implementação do AI Process de validação de dados em seu Carol App, o mesmo pode ser executado em qualquer tenant que possua uma versão/release do Carol App que já possua o mesmo implementado. Ao executar o AI Process de validação de dados, o mesmo criará uma task onde serão exibidos todos os logs contendo FAIL, WARN ou ERROR enviados pelo dbt, além do sumário final mostrando quantos testes foram executados e o resultado totalizado dos mesmos.

Ao final da task, será gerado um relatório completo com o resultado de todos os testes, que serão depositados dentro do storage do Carol App da tenant que executou a task de validação de dados. Esse relatório conterá o retorno completo do dbt ao executar o comando tests descrito anteriormente e estará dentro de uma pasta de nome data-validation. O formato do nome dos arquivos será:

data_validation_tests_{TASK_ID}__{CURRENT_TIMESTAMP}

Exemplo:

data_validation_tests_37c09a7cc8c54b34999c47415f6ab36a__2023-12-05_14:37:54.792532.txt

Enviando os resultados para um WebHook

O resumo dos resultados da validação de dados podem ser enviados para WebHooks. Para isso, adicione em seu Carol App um setting com nome data_validation_webhook do tipo STRING e preencha o valor com a URL do mesmo. Abaixo temos um exemplo do App Setting que deve ser criado.

Importante

Os WebHooks homologados atualmente são Slack e Google Chat. Outros WebHooks podem ser inseridos no Carol App Setting, mas podem não enviar a mensagem corretamente.

Caso seu Carol App tenha o Setting conforme descrito acima, logs adicionais serão mostrados na task de processamento de validação de dados. Caso haja erro no envio da mensagem para o WebHook, será gerado um log de Warning dentro da task, porém não irá falhar a mesma. Um exemplo de envio com sucesso pode ser verificado na imagem abaixo.

Abaixo temos um exemplo de mensagem que é enviada para o espaço que corresponde ao WebHook.

Tempo de retenção de reports

Os relatórios tem um tempo de retenção padrão de 7 dias corridos e serão excluídos na próxima execução do processo de validação de dados após completarem 7 dias de sua geração.

Deleted data validation file data-validation/data_validation_tests_2023-11-17_15:27:23.528415.txt (Retention Policy).

Guidelines

Como o dbt executa validações utilizando SQL dentro do dataset BigQuery da tenant, é necessário estar ciente de que todas as validações criadas irão gerar jobs que consomem slots do BigQuery, então a preocupação com o recurso deve estar em mente. Dessa forma, seguem abaixo guidelines para construção e utilização de testes dentro da plataforma Carol.

• Valide apenas dados e regras essenciais para o negócio. Validações de dados secundários ou não prioritários irá consumir recursos desnecessariamente.
• Utilize apenas os testes necessários para validação dos dados. Testar os dados de múltiplas formas irá gerar uma maior quantidade de jobs, assim consumindo recursos desnecessariamente.
• Para uma menor concorrência com jobs de SQL Process da plataforma, todos os jobs de validação de dados são enviados com prioridade BATCH.

Guidelines para SQL personalizado

Caso utilize SQL personalizado para validação dos dados, otimize as consultas de forma a consumir a menor quantidade de dados possível. No caso abaixo, está sendo testado se o campo devicecode de uma tabela é valido quando comparado com o mesmo campo na tabela device. Para testagens não é necessário retornar o campo ou uma transformação, apenas o retorno true já é suficiente para que o dbt detecte que se o teste passou ou não. Além disso, foi utilizado um pequeno número de consultas e o left join como alternativa para utilizar a menor quantidade de recursos possível. Para validar quantos recursos seu teste está utilizando, é possível consultar o Plano de Execução.

    {% test is_valid_device(model) %}

    with validation as (

        select true 
        from 
        {{ model }} c
        left join {{ source('clockin','device') }} d on d.devicecode = c.devicecode 
        where e.devicecode is null

    ),

    validation_errors as (

    select * from validation
    )

    select *
    from validation_errors

    {% endtest %}

Importante

A notação utilizada em testes SQL personalizado para referenciar dinâmicamente tabelas do dataset é a notação Jinja.