Avaliação de Qualidade de Dados (Menthor DB)

O motor de auditoria do Menthor DB realiza uma análise técnica e semântica nas tabelas de banco de dados vinculadas a um contexto. O objetivo é garantir que os dados estejam íntegros e que os metadados sejam claros o suficiente para a geração precisa de consultas SQL.

Funcionamento do Diagnóstico

Diferente das operações de ingestão, este endpoint é síncrono e utiliza processamento paralelo para avaliar todas as tabelas do esquema simultaneamente.

  1. Extração de Schema: O sistema recupera as definições de tabelas e colunas associadas ao id_context.

  2. Métricas Técnicas: Calcula scores estatísticos como completitude (completeness), unicidade (uniqueness) e aderência ao schema.

  3. Análise Qualitativa (LLM): A IA avalia se os nomes de tabelas e descrições de colunas são ambíguos ou se precisam de mais contexto para evitar erros de interpretação.

  4. Consolidação: Gera um relatório único que separa sucessos de falhas técnicas.

Detalhamento das Métricas de Auditoria

O Menthor DB utiliza algoritmos estatísticos aplicados sobre uma amostra (default: 200 linhas) para extrair os seguintes indicadores:

  • Completitude (20% do peso): Calculada pela razão de células não-nulas. .. math:: (1 - frac{nulos}{total_celulas}) times 10

  • Unicidade (20% do peso): Avalia a taxa de duplicidade de linhas na amostra. .. math:: (1 - frac{duplicados}{total_linhas}) times 10

  • Aderência ao Schema (30% do peso): Verifica se o tipo de dado real no banco (ex: int64) corresponde ao tipo declarado no metadado (ex: integer).

  • Design Semântico - LLM (30% do peso): Avaliação qualitativa que julga se a nomenclatura e descrições permitem que um humano (ou a própria IA) entenda o propósito dos dados sem ambiguidade.

Interpretando o Score de Qualidade

O campo overall_score (0.0 a 10.0) reflete a confiabilidade dos dados para uso em linguagem natural.

Régua de Maturidade Menthor DB

Score

Diagnóstico e Ação

> 9.0

Dados Prontos: Alta precisão em SQL automático e geração de insights analíticos.

6.0 a 8.9

Ajustes Necessários: Siga as suggestions da IA para renomear colunas técnicas ou enriquecer descrições.

< 6.0

Inconsistente: Alto risco de alucinações da IA. Os dados podem estar mal estruturados ou faltar metadados básicos.

Resiliência do Relatório

O endpoint utiliza uma abordagem de sucesso parcial para garantir que uma única tabela corrompida não impeça a análise do restante do banco de dados:

  • Relatórios bem-sucedidos: Listados em table_reports.

  • Relatórios de falha: Listados em failed_reports, contendo o erro técnico específico que impediu a análise daquela tabela (ex: falha de conexão ou timeout).

Importante

Esta avaliação deve ser realizada sempre que houver mudanças estruturais no banco de dados (DDL) ou após o uso do endpoint /databases/receive_documents_db.

Limites e Performance

  • Rate Limiting: O endpoint é protegido para evitar picos de custo com LLM.

  • Timeout: Em contextos com dezenas de tabelas, o tempo de resposta pode ser maior devido ao processamento paralelo de cada diagnóstico.