Gravar resultados de qualidade de dados em tabelas do Data Catalog

Você pode configurar as execuções de avaliação do AWS Glue Data Quality para gravar automaticamente os resultados em tabelas Apache Iceberg no AWS Glue Data Catalog. Depois de habilitar a saída de resultados, você pode consultar os resultados de qualidade de dados diretamente usando , montar painéis com ferramentas de visualização e manter um histórico centralizado dos resultados de qualidade de dados de toda a sua conta.

Você pode gravar os seguintes tipos de resultados de qualidade de dados nas tabelas do Data Catalog:

Pré-requisitos

Para gravar resultados de qualidade de dados nas tabelas do Data Catalog, o perfil do IAM usado na execução da avaliação deverá ter as seguintes permissões:

A execução da avaliação usa o perfil do IAM especificado para gravar nas tabelas de resultados. Esse é o mesmo perfil que tem acesso à tabela de origem dos dados.

Configurar a saída de resultados

Você configura a saída dos resultados de qualidade de dados usando o parâmetro --additional-run-options da API StartDataQualityRulesetEvaluationRun ou o parâmetro additional_options nos trabalhos do AWS Glue ETL. Por padrão, o AWS Glue Data Quality não grava os resultados nas tabelas do Data Catalog. Habilite explicitamente cada tipo de resultado que desejar gravar.

Cada tipo de resultado tem seu próprio bloco de configuração com uma estrutura CatalogTableConfig compartilhada. Se você não fornecer uma CatalogTableConfig, o AWS Glue Data Quality derivará os valores padrão automaticamente, inclusive o nome da tabela e o caminho do Amazon S3.

A estrutura CatalogTableConfig contém os seguintes campos:

Exemplo: configurar os resultados de regras e os resultados de perfilamento

aws glue start-data-quality-ruleset-evaluation-run \
  --data-source '{
    "GlueTable": {
      "DatabaseName": "my_database",
      "TableName": "my_table"
    }
  }' \
  --role "arn:aws:iam::123456789012:role/GlueServiceRole" \
  --ruleset-names '["my_ruleset"]' \
  --additional-run-options '{
    "DataQualityRuleResults": {
      "WriteDataQualityRuleResultsEnabled": true,
      "CatalogTableConfig": {
        "DatabaseName": "quality_results",
        "TableName": "rule_results"
      }
    },
    "ProfilingResults": {
      "WriteProfilingResultsEnabled": true,
      "CatalogTableConfig": {
        "DatabaseName": "quality_results",
        "TableName": "profiles"
      }
    }
  }'

Exemplo: configurar os resultados no nível da linha

Para resultados no nível da linha, é possível também especificar o tipo dos registros a serem incluídos e o número máximo de linhas a serem gravadas.

aws glue start-data-quality-ruleset-evaluation-run \
  --data-source '{
    "GlueTable": {
      "DatabaseName": "my_database",
      "TableName": "my_table"
    }
  }' \
  --role "arn:aws:iam::123456789012:role/GlueServiceRole" \
  --ruleset-names '["my_ruleset"]' \
  --additional-run-options '{
    "RowLevelResults": {
      "MaxRowsToWrite": 5000,
      "ResultType": "FAILED_ONLY",
      "CatalogTableConfig": {
        "DatabaseName": "quality_results",
        "TableName": "row_level_results"
      }
    }
  }'

O parâmetro ResultType aceita os seguintes valores:

Exemplo: configurar em trabalhos de ETL do AWS Glue

Nos trabalhos de ETL do AWS Glue, você configura a saída de resultados usando o parâmetro additional_options com chaves em notação de pontos:

result = EvaluateDataQuality.process_rows(
    frame=dynamic_frame,
    ruleset=ruleset,
    publishing_options={
        "dataQualityEvaluationContext": "my_context",
        "enableDataQualityResultsPublishing": True
    },
    additional_options={
        "observations.scope": "ALL",
        "dataQualityResultsPublishing.strategy": "BEST_EFFORT",
        "dataQualityResultsPublishing.resultsFormat.profilingResults.writeProfilingResultsEnabled": "true",
        "dataQualityResultsPublishing.resultsFormat.profilingResults.catalogTableConfig.databaseName": "my_db",
        "dataQualityResultsPublishing.resultsFormat.profilingResults.catalogTableConfig.tableName": "profiling_results",
        "dataQualityResultsPublishing.resultsFormat.profilingResults.catalogTableConfig.s3Location": "s3://amzn-s3-demo-bucket/profiling/",
        "dataQualityResultsPublishing.resultsFormat.profilingResults.catalogTableConfig.catalogId": "123456789012"
    }
)

Exemplo: configurar resultados de observação

Você pode configurar os resultados de observação da mesma forma que outros tipos de resultados. Os resultados de observação exigem que a detecção de anomalias seja habilitada (ObservationScope: ALL):

aws glue start-data-quality-ruleset-evaluation-run \
  --data-source '{
    "GlueTable": {
      "DatabaseName": "my_database",
      "TableName": "my_table"
    }
  }' \
  --role "arn:aws:iam::123456789012:role/GlueServiceRole" \
  --ruleset-names '["my_ruleset"]' \
  --additional-run-options '{
    "ObservationScope": "ALL",
    "ObservationResults": {
      "WriteObservationResultsEnabled": true,
      "CatalogTableConfig": {
        "DatabaseName": "quality_results",
        "TableName": "observation_results"
      }
    }
  }'

Esquemas de tabela

O AWS Glue Data Quality grava cada tipo de resultado em uma tabela Iceberg separada. Os resultados de regras, os resultados de perfilamento (incluindo a tabela de resultados de distribuição separada) e as tabelas de resultados de observação são particionados por catalog_id, database_name, table_name e day(stored_on) para permitir consultas eficientes. Você pode filtrar por stored_on diretamente para consultas baseadas em hora e o Iceberg lida com a remoção de partições automaticamente.

Tabela de resultados de regras

A tabela de resultados da regras armazena o resultado de aprovação ou reprovação em cada regra avaliada durante uma execução de qualidade de dados.

Tabela de resultados de perfilamento

A tabela a seguir descreve as colunas da tabela de resultados de perfilamento. Essa tabela armazena estatísticas escalares coletadas por analisadores e regras (como Mean, StandardDeviation e Completeness). O AWS Glue Data Quality armazena estatísticas de distribuição em uma tabela de resultados de distribuição separada.

Tabela de resultados de distribuição

A tabela a seguir descreve as colunas da tabela de resultados de distribuição. Os resultados de distribuição são armazenados separadamente das estatísticas de perfilamento escalar, com uma linha para cada compartimento ou categoria. Você pode configurar essa tabela dentro do bloco ProfilingResults.DistributionResults.

Tabela de resultados no nível da linha

A tabela a seguir descreve as colunas da tabela de resultados no nível da linha. Você pode usar essa tabela para identificar os registros específicos que foram reprovados pelas regras de qualidade de dados.

Tabela de resultados de observação

A tabela de resultados de observação armazena as previsões de detecção de anomalias para cada estatística em toda execução da avaliação. A tabela inclui todos os resultados des previsões: anomalias, valores normais e previsões ignoradas. Isso permite renderizar gráficos de tendências contínuas com faixas de previsão.

Consultar resultados com

Depois que a avaliação de qualidade de dados é concluída, é possível consultar as tabelas de resultados diretamente usando . Os exemplos a seguir demonstram padrões comuns de consulta.

Exemplo: encontrar regras reprovadas em uma execução específica

SELECT rule_name, rule_description, evaluation_message, evaluated_metrics
FROM quality_results.rule_results
WHERE ruleset_evaluation_run_id = 'dqr-12345678'
  AND rule_result = 'FAIL'
ORDER BY rule_name;

Exemplo: visualizar estatísticas de perfilamento ao longo do tempo

SELECT stored_on, statistics_value
FROM quality_results.profiles
WHERE database_name = 'my_database'
  AND table_name = 'my_table'
  AND statistic_name = 'Mean'
  AND columns_referenced = ARRAY['salary']
ORDER BY stored_on;

Exemplo: identificar linhas que foram reprovadas em uma regra específica

SELECT *
FROM quality_results.row_level_results
WHERE data_quality_evaluation_result = 'Failed'
  AND contains(data_quality_rules_fail, 'IsComplete "email"');

Exemplo: visualizar um histograma numérico

SELECT bin_index, bin_lower_bound, bin_upper_bound, bin_count
FROM quality_results.distributions
WHERE column_name = 'salary'
  AND ruleset_evaluation_run_id = 'dqrun-abc123'
ORDER BY bin_index;

Exemplo: visualizar uma distribuição categórica de valores

SELECT bin_label, bin_count
FROM quality_results.distributions
WHERE column_name = 'department'
  AND ruleset_evaluation_run_id = 'dqrun-abc123'
ORDER BY bin_count DESC;

Exemplo: acompanhar a frequência da categoria ao longo do tempo

SELECT started_on, bin_count
FROM quality_results.distributions
WHERE column_name = 'status' AND bin_label = 'active'
ORDER BY started_on;

Exemplo: visualizar tendências de detecção de anomalias com faixas de previsão

SELECT o.recorded_on, 
       p.statistics_value AS actual_value,
       o.expected_value, 
       o.lower_bound, 
       o.upper_bound,
       o.prediction_outcome
FROM quality_results.profiles p
JOIN quality_results.observation_results o
  ON p.statistic_id = o.statistic_id
  AND p.ruleset_evaluation_run_id = o.ruleset_evaluation_run_id
WHERE p.database_name = 'my_database'
  AND p.table_name = 'my_table'
  AND p.statistic_name = 'RowCount'
  AND p.stored_on >= DATE '2025-03-01'
ORDER BY p.stored_on;

Exemplo: consultar o estado da observação mais recente após as anotações

Como a tabela de resultados de observação usa um modelo somente acréscimo, as anotações de exclusão adicionam novas linhas. Use uma consulta de desduplicação para obter o estado mais recente de cada observação:

SELECT statistic_id, statistic_name, prediction_outcome, 
       expected_value, lower_bound, upper_bound, training_input, stored_on
FROM (
  SELECT *, ROW_NUMBER() OVER (
    PARTITION BY statistic_id, ruleset_evaluation_run_id 
    ORDER BY stored_on DESC
  ) AS rn
  FROM quality_results.observation_results
  WHERE database_name = 'my_database'
    AND table_name = 'my_table'
)
WHERE rn = 1
ORDER BY stored_on;

Considerações

Leve em conta as seguintes considerações ao gravar resultados de qualidade de dados em tabelas do Data Catalog: