Referência de Data Quality Definition Language (DQDL)

Data Quality Definition Language (DQDL) é uma linguagem específica de domínio que você usa para definir regras para o AWS Glue Data Quality.

Este guia apresenta os principais conceitos de DQDL para ajudar você a entender a linguagem. Ele também fornece uma referência para tipos de regras DQDL com sintaxe e exemplos. Antes de usar este guia, recomendamos que você se familiarize com o AWS Glue Data Quality. Para obter mais informações, consulte AWS Glue Data Quality.

Sintaxe DQDL

Um documento DQDL diferencia maiúsculas de minúsculas e contém um conjunto de regras que agrupa regras individuais de qualidade de dados. Para estruturar um conjunto de regras, você deve criar uma lista denominada Rules (em maiúsculas), delimitada por colchetes. A lista deve conter uma ou mais regras DQDL separadas por vírgula, como no exemplo a seguir.

Rules = [
   IsComplete "order-id",
   IsUnique "order-id"
]

Estrutura da regra

A estrutura de uma regra DQDL depende do tipo de regra. No entanto, as regras DQDL geralmente se encaixam no formato a seguir.

<RuleType> <Parameter> <Parameter> <Expression>

RuleType é o nome com distinção entre maiúsculas e minúsculas do tipo de regra que você quer configurar. Por exemplo, IsComplete, IsUnique ou CustomSql. Os parâmetros da regra diferem para cada tipo de regra. Para obter uma referência completa dos tipos de regras DQDL e seus parâmetros, consulte Referência de tipos de regra DQDL.

Regras compostas

Você pode usar o mesmo operador para conectar várias regras, portanto, a combinação de regras a seguir é permitida.

(Mean "Star_Rating" > 3) and (Mean "Order_Total" > 500) and (IsComplete "Order_Id")

Você pode combinar os operadores lógicos em uma única expressão. Por exemplo:

(Mean "Star_Rating" > 3) and ((Mean "Order_Total" > 500) or (IsComplete "Order_Id"))

Você também pode criar regras mais complexas e aninhadas.

(RowCount > 0) or ((IsComplete "colA") and (IsUnique "colA"))

Como as regras compostas funcionam

Por padrão, as regras compostas são avaliadas como regras individuais em todo o conjunto de dados ou tabela e, em seguida, os resultados são combinados. Em outras palavras, a coluna inteira é avaliada primeiro e, em seguida, o operador é aplicado. Esse comportamento padrão é explicado abaixo com um exemplo:

# Dataset

+------+------+
|myCol1|myCol2|
+------+------+
|     2|     1|
|     0|     3|
+------+------+

# Overall outcome

+----------------------------------------------------------+-------+
|Rule                                                      |Outcome|
+----------------------------------------------------------+-------+
|(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)|Failed |
+----------------------------------------------------------+-------+
      

No exemplo acima, o AWS Glue Data Quality avalia primeiro (ColumnValues "myCol1" > 1), o que resultará em uma falha. Em seguida, ele avaliará (ColumnValues "myCol2" > 2), que também falhará. A combinação de ambos os resultados será anotada como FALHA.

No entanto, se você preferir um comportamento semelhante ao SQL, em que a linha inteira deve ser avaliada, é necessário definir explicitamente o parâmetro ruleEvaluation.scope conforme mostrado em additionalOptions no trecho de código abaixo.

object GlueApp {
  val datasource = glueContext.getCatalogSource(
    database="<db>",
    tableName="<table>",
    transformationContext="datasource"
  ).getDynamicFrame()

  val ruleset = """
    Rules = [
        (ColumnValues "age" >= 26) OR (ColumnLength "name" >= 4)        
    ]
  """

  val dq_results = EvaluateDataQuality.processRows(
    frame=datasource,
    ruleset=ruleset,
    additionalOptions=JsonOptions("""
        {
          "compositeRuleEvaluation.method":"ROW"
        }
      """
    )
  )
}     
      

No Catálogo de Dados do AWS Glue, é possível configurar facilmente essa opção na interface do usuário, conforme demonstrado abaixo.

Depois de definidas, as regras compostas se comportarão como uma única regra avaliando a linha inteira. O exemplo a seguir ilustra esse comportamento.

# Row Level outcome

+------+------+------------------------------------------------------------+---------------------------+
|myCol1|myCol2|DataQualityRulesPass                                        |DataQualityEvaluationResult|
+------+------+------------------------------------------------------------+---------------------------+
|2     |1     |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed                     |
|0     |3     |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed                     |
+------+------+------------------------------------------------------------+---------------------------+     
      

Algumas regras não podem ser aceitas nesse recurso porque seu resultado geral depende de limites ou proporções. Elas estão listadas abaixo.

Regras baseadas em índices:

Regras dependentes de limites:

Quando as regras a seguir incluem limites, elas não são aceitas. No entanto, as regras que não envolvem with threshold permanecem válidas.

Expressões

Se um tipo de regra não produzir uma resposta booliana, você deverá fornecer uma expressão como parâmetro para criar uma resposta booliana. Por exemplo, a regra a seguir verifica a média de todos os valores em uma coluna em relação a uma expressão para retornar um resultado verdadeiro ou falso.

Mean "colA" between 80 and 100

Alguns tipos de regras, como IsUnique e IsComplete já retornam uma resposta booleana.

A tabela a seguir lista as expressões que você pode usar nas regras DQDL.

Completeness "colA" = "1.0",
ColumnValues "colA" = "2022-06-30"

ColumnValues "colA" != "a",
ColumnValues "colA" != "2022-06-30"

ColumnValues "colA" > 10

ColumnValues "colA" < 1000,
ColumnValues "colA" < "2022-06-30"

ColumnValues "colA" >= 10

ColumnValues "colA" <= 1000

Mean "colA" between 8 and 100,
ColumnValues "colA" between "2022-05-31" and "2022-06-30"

ColumnValues "colA" not between "2022-05-31" and "2022-06-30"

ColumnValues "colA" in [ 1, 2, 3 ],
ColumnValues "colA" in [ "a", "b", "c" ]

ColumnValues "colA" not in [ 1, 2, 3 ],
ColumnValues "colA" not in [ "a", "b", "c" ]

ColumnValues "colA" matches "[a-zA-Z]*"

ColumnValues "colA" not matches "[a-zA-Z]*"

ColumnValues "load_date" > (now() - 3 days)

ColumnValues "colA" in ["A", "B"] with threshold > 0.8,
ColumnValues "colA" matches "[a-zA-Z]*" with threshold between 0.2 and 0.9
ColumnDataType "colA" = "Timestamp" with threshold > 0.9

Palavras-chave para NULL, EMPTY e WHITESPACES_ONLY

Se desejar validar se uma coluna de string tem uma string nula, vazia ou apenas com espaços em branco, você pode usar as seguintes palavras-chave:

Para uma expressão numérica ou baseada em data, se você quiser validar se uma coluna tem um valor nulo, poderá usar as palavras-chave a seguir.

Filtragem com a cláusula Where

Você pode filtrar seus dados ao criar regras. Isso é útil quando você quiser aplicar regras condicionais.

<DQDL Rule> where "<valid SparkSQL where clause> "

É necessário especificar o filtro com a palavra-chave where, seguida por uma instrução válida do SparkSQL entre aspas ("").

Se você quiser adicionar a cláusula where a uma regra com um limite, será necessário especificar a cláusula where antes da condição de limite.

<DQDL Rule> where "valid SparkSQL statement>" with threshold <threshold condition>
        

Com essa sintaxe, você pode escrever regras como as seguintes.

Completeness "colA" > 0.5 where "colB = 10"
ColumnValues "colB" in ["A", "B"] where "colC is not null" with threshold > 0.9
ColumnLength "colC" > 10 where "colD != Concat(colE, colF)"

Vamos validar se a instrução do SparkSQL fornecida é válida. Se for inválida, a avaliação da regra falhará e lançaremos o IllegalArgumentException com o seguinte formato:

Rule <DQDL Rule> where "<invalid SparkSQL>" has provided an invalid where clause :
<SparkSQL Error>

Comportamento da cláusula where quando a identificação do registro de erro no nível de linha estiver ativada

Com o AWS Glue Data Quality, você pode identificar registros específicos que falharam. Ao aplicar uma cláusula where às regras compatíveis com resultados no nível de linha, rotularemos como Passed as linhas que forem filtradas pela cláusula where.

Se você preferir rotular separadamente as linhas filtradas como SKIPPED, defina o seguinte additionalOptions para a tarefa de ETL.

object GlueApp {
  val datasource = glueContext.getCatalogSource(
    database="<db>",
    tableName="<table>",
    transformationContext="datasource"
  ).getDynamicFrame()

  val ruleset = """
    Rules = [
       IsComplete "att2" where "att1 = 'a'"        
    ]
  """

  val dq_results = EvaluateDataQuality.processRows(
    frame=datasource,
    ruleset=ruleset,
    additionalOptions=JsonOptions("""
        {
          "rowLevelConfiguration.filteredRowLabel":"SKIPPED"
        }
      """
    )
  )
}

Como exemplo, consulte a regra e o quadro de dados a seguir:

IsComplete att2 where "att1 = 'a'"

Constantes

No DQDL, você pode definir valores constantes e referenciá-los em todo o script. Isso ajuda a evitar problemas relacionados aos limites de tamanho da consulta, por exemplo, ao trabalhar com instruções SQL grandes que podem exceder os limites permitidos. Ao atribuir esses valores a constantes, você pode simplificar seu DQDL e evitar atingir esses limites.

O exemplo a seguir mostra como definir e usar uma constante:

mySql = "select count(*) from primary"

Rules = [
    CustomSql $mySql between 0 and 100
]

Neste exemplo, a consulta SQL é atribuída à constante mySql, que é então referenciada na regra usando o prefixo $.

Rótulos

Os rótulos fornecem uma maneira eficaz de organizar e analisar os resultados de qualidade dos dados. Você pode consultar os resultados por rótulos específicos para identificar regras com falhas em categorias específicas, contar os resultados das regras por equipe ou domínio e criar relatórios focados para diferentes partes interessadas.

Por exemplo, você pode aplicar todas as regras que dizem respeito à equipe financeira com um rótulo "team=finance" e gerar um relatório personalizado para mostrar métricas de qualidade específicas para a equipe financeira. Você pode rotular regras de alta prioridade como "criticality=high" para priorizar os esforços de remediação. Os rótulos podem ser criados como parte do DQDL. Você pode consultar os rótulos como parte dos resultados das regras, resultados em nível de linha e respostas da API, facilitando a integração com seus fluxos de trabalho de monitoramento e geração de relatórios existentes.

Sintaxe para rótulos DQDL

O DQDL oferece suporte a rótulos padrão e específicos de regras. Os rótulos padrão são definidos no nível do conjunto de regras e se aplicam automaticamente a todas as regras dele. As regras individuais também podem ter seus próprios rótulos e, como os rótulos são implementados como pares de chave-valor, os rótulos específicos da regra podem substituir os rótulos padrão ao usar a mesma chave.

O exemplo a seguir mostra como usar rótulos padrão e específicos para regras:

DefaultLabels=["frequency"="monthly"]

Rules = [
    // Auto includes the default label ["frequency"="monthly"]
    ColumnValues "col" > 21,
    // Add ["foo"="bar"] to default label. Labels for this rule would be ["frequency"="monthly", "foo"="bar"]
    Rule 1 with threshold > 0.8 labels=["foo"="bar"],
    // Override default label. Labels for this rule would be ["frequency"="daily", "foo"="bar"]
    Rule 2 with threshold > 0.8 labels=["foo"="bar", "frequency"="daily"]
    // Labels must be applied to the entire composite rule (parentheses required)
    (Rule 1 AND Rule 2) labels=["foo"="bar]
]

Restrições do rótulo

Os rótulos têm as seguintes restrições:

Recuperar rótulos DQDL

Você pode recuperar rótulos DQDL de resultados de regras, resultados em nível de linha e respostas de API.

Resultados da regra

Os rótulos DQDL estão sempre visíveis nos resultados das regras. Nenhuma configuração adicional é necessária para habilitá-los.

Resultados por linha

Os rótulos DQDL são desabilitados por padrão nos resultados em nível de linha, mas podem ser habilitados usando as AdditionalOptions no EvaluateDataQuality.

O exemplo a seguir mostra como habilitar rótulos em resultados por linha:

val evaluateResult = EvaluateDataQuality.processRows(
    frame=AmazonS3_node1754591511068,
    ruleset=example_ruleset,
    publishingOptions=JsonOptions("""{
        "dataQualityEvaluationContext": "evaluateResult",
        "enableDataQualityCloudWatchMetrics": "true",
        "enableDataQualityResultsPublishing": "true"
    }"""),
    additionalOptions=JsonOptions("""{
        "performanceTuning.caching":"CACHE_NOTHING",
        "observations.scope":"ALL",
        "rowLevelConfiguration.ruleWithLabels":"ENABLED"
    }""")
)

Quando habilitado, o quadro de dados de resultados em nível de linha inclui rótulos para cada regra nas colunas DataQualityRulesPass, DataQualityRulesFail e DataQualityRulesSkip.

Resposta da API

Os rótulos DQDL estão sempre visíveis nas respostas da API em um novo campo Labels no objeto RuleResults.

O exemplo a seguir mostra os rótulos em uma resposta da API:

{
    "ResultId": "dqresult-example",
    "ProfileId": "dqprofile-example",
    "Score": 0.6666666666666666,
    "RulesetName": "EvaluateDataQuality_node1754591514205",
    "EvaluationContext": "EvaluateDataQuality_node1754591514205",
    "StartedOn": "2025-08-22T19:36:10.448000+00:00",
    "CompletedOn": "2025-08-22T19:36:16.368000+00:00",
    "JobName": "anniezc-test-labels",
    "JobRunId": "jr_068f6d7a45074d9105d14e4dee09db12c3b95664b45f6ee44fa29ed7e5619ba8",
    "RuleResults": [
        {
            "Name": "Rule_0",
            "Description": "IsComplete colA",
            "EvaluationMessage": "Input data does not include column colA!",
            "Result": "FAIL",
            "EvaluatedMetrics": {},
            "EvaluatedRule": "IsComplete colA",
            "Labels": {
                "frequency": "monthly"
            }
        },
        {
            "Name": "Rule_1",
            "Description": "Rule 1 with threshold > 0.8",
            "Result": "PASS",
            "EvaluatedMetrics": {},
            "EvaluatedRule": "Rule 1 with threshold > 0.8",
            "Labels": {
                "frequency": "monthly",
                "foo": "bar"
            }
        },
        {
            "Name": "Rule_3",
            "Description": "Rule 2 with threshold > 0.8",
            "Result": "PASS",
            "EvaluatedMetrics": {},
            "EvaluatedRule": "Rule 2 with threshold > 0.8",
            "Labels": {
                "frequency": "daily",
                "foo": "bar"
            }
        }
    ]
}

Regras dinâmicas

Agora é possível criar regras dinâmicas para comparar as métricas atuais produzidas por suas regras com seus valores históricos. Essas comparações históricas são habilitadas ao usar o operador last() em expressões. Por exemplo, a regra RowCount > last() terá êxito quando o número de linhas na execução atual for maior do que a contagem de linhas anterior mais recente para o mesmo conjunto de dados. last() usa um argumento opcional de número natural que descreve quantas métricas anteriores devem ser consideradas; last(k) em que k >= 1 fará referência às últimas k métricas.

Para formar expressões válidas, use last(k), em que k > 1 requer uma função de agregação para reduzir vários resultados históricos a um único número. Por exemplo, RowCount > avg(last(5)) verificará se a contagem de linhas do conjunto de dados atual é estritamente maior do que a média das últimas cinco contagens de linhas do mesmo conjunto de dados. RowCount > last(5) produzirá um erro porque a contagem de linhas do conjunto de dados atual não pode ser comparada de forma significativa a uma lista.

Funções de agregação compatíveis:

Exemplos de expressões

ColumnCorrelation

DistinctValuesCount

A maioria dos tipos de regras com condições ou limites numéricos é compatível com as regras dinâmicas. Consulte a tabela fornecida, Analisadores e regras, para determinar se as regras dinâmicas são compatíveis com seu tipo de regra.

Exclusão de estatísticas das regras dinâmicas

Às vezes, você precisará excluir estatísticas de dados dos cálculos das regras dinâmicas. Digamos que você tenha feito um carregamento de dados históricos e não queira que isso afete as médias. Para fazer isso, abra o trabalho no ETL do AWS Glue e escolha a guia Qualidade de dados, em seguida escolha Estatísticas e selecione as estatísticas que você deseja excluir. Você poderá ver um gráfico de tendências com uma tabela de estatísticas. Selecione os valores que você deseja excluir e escolha Excluir estatísticas. Agora, as estatísticas excluídas não serão consideradas nos cálculos dinâmicos das regras.

Analisadores

As regras de DQDL usam funções chamadas analisadores para coletar informações sobre seus dados. Essas informações são empregadas por uma expressão booleana da regra para determinar se a regra terá êxito ou não. Por exemplo, a regra RowCount RowCount > 5 usará um analisador de contagem de linhas para descobrir o número de linhas em seu conjunto de dados e comparar essa contagem com a expressão > 5 para verificar se existem mais de cinco linhas no conjunto de dados atual.

Às vezes, em vez de criar regras, recomendamos criar analisadores e depois fazer com que eles gerem estatísticas que possam ser usadas para detectar anomalias. Para esses casos, será necessário criar analisadores. Os analisadores diferem das regras nas seguintes maneiras:

Os analisadores podem existir de forma independente, sem a necessidade de regras, permitindo a configuração rápida e a construção progressiva de regras de qualidade de dados.

Alguns tipos de regras podem ser inseridos no bloco de Analyzers do seu conjunto de regras para executar as regras necessárias para os analisadores e coletar informações sem aplicar verificações para nenhuma condição. Alguns analisadores não estão associados a regras e só podem ser inseridos no bloco de Analyzers. A tabela a seguir indica se cada item é compatível como uma regra ou como um analisador independente, junto com detalhes adicionais para cada tipo de regra.

Exemplo de conjunto de regras com o analisador

O seguinte conjunto de regras usa:

Os resultados das métricas do analisador podem ser visualizados na guia Data Quality da execução do trabalho.

Rules = [
   RowCount > avg(last(3))
]
Analyzers = [
   DistinctValuesCount "Name",
   ColumnLength "Name"
]     
        

O AWS Glue Data Quality é compatível com os seguintes analisadores.

Comentários

É possível usar o caractere "#" para adicionar um comentário ao seu documento DQDL. Qualquer coisa após o caractere "#" e até o final da linha é ignorada pelo DQDL.

Rules = [
    # More items should generally mean a higher price, so correlation should be positive
    ColumnCorrelation "price" "num_items" > 0
]