Referencia del lenguaje de definición de calidad de datos (DQDL)

El lenguaje de definición de calidad de datos (DQDL) es un lenguaje específico de un dominio que se utiliza para definir las reglas de Calidad de datos de AWS Glue.

En esta guía, se presentan los conceptos clave de DQDL para entender el lenguaje. También proporciona una referencia para los tipos de reglas de DQDL con sintaxis y ejemplos. Antes de utilizar esta guía, le recomendamos que se familiarice con Calidad de datos de AWS Glue. Para obtener más información, consulte Calidad de datos de AWS Glue.

Sintaxis de DQDL

Un documento de DQDL distingue entre mayúsculas y minúsculas y contiene un conjunto de reglas que agrupa las reglas individuales de la calidad de los datos. Para crear un conjunto de reglas, debe crear una lista denominada Rules (en mayúscula), delimitada por un par de corchetes. La lista debe contener una o más reglas de DQDL separadas por comas, como en el ejemplo siguiente.

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

Estructura de la regla

La estructura de una regla de DQDL depende del tipo de regla. Sin embargo, las reglas de DQDL se suelen ajustar al siguiente formato.

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

RuleType es el nombre que distingue entre mayúsculas y minúsculas del tipo de regla que quiere configurar. Por ejemplo, IsComplete, IsUnique o CustomSql. Los parámetros de la regla son diferentes para cada tipo de regla. Para obtener una referencia completa de los tipos de reglas de DQDL y sus parámetros, consulte Referencia de tipo de regla de DQDL.

Reglas compuestas

Puede utilizar el mismo operador para conectar varias reglas, por lo que se permite la siguiente combinación de reglas.

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

Puede combinar los operadores lógicos en una sola expresión. Por ejemplo:

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

También puede crear reglas anidadas más complejas.

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

Funcionamiento de las reglas compuestas

De manera predeterminada, las reglas compuestas son evaluadas como reglas individuales a lo largo de todo el conjunto de datos y de la tabla y luego se combinan los resultados. En otras palabras, primero evalúan toda la columna y, a continuación, aplican el operador. Este comportamiento predeterminado se explica a continuación con un ejemplo:

# Dataset

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

# Overall outcome

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

En el ejemplo anterior, AWS Glue Data Quality primero evalúa (ColumnValues "myCol1" > 1), lo cual resultará en una falla. Luego evaluará (ColumnValues "myCol2" > 2), que también fallará. La combinación de los dos resultados se indicará como fallida.

Sin embargo, si prefiere SQL como el comportamiento en caso de que necesite evaluar una fila entera, tiene que establecer de manera explícita el parámetro ruleEvaluation.scope como se muestra en additionalOptions, en el fragmento de código a continuación.

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"
        }
      """
    )
  )
}     
      

En Catálogo de datos de AWS Glue, puede configurar fácilmente esta opción en la interfaz de usuario, como se muestra a continuación.

Una vez establecidas, las reglas compuestas se comportarán como una regla única que evalúa la fila en su totalidad. En el ejemplo a continuación se muestra este comportamiento.

# 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                     |
+------+------+------------------------------------------------------------+---------------------------+     
      

Algunas reglas no son compatibles con esta característica debido a que los resultados generales se basan en umbrales o proporciones. Estas regulas se enumeran a continuación.

Reglas que se basan en las proporciones:

Reglas que se basan en los umbrales:

Cuando las reglas que se mencionan a continuación incluyen con un umbral, no son compatibles. Sin embargo, las reglas que no incluyen with threshold sí mantienen la compatibilidad.

Expresiones

Si un tipo de regla no produce una respuesta booleana, debe proporcionar una expresión como parámetro para crear una respuesta booleana. Por ejemplo, la siguiente regla compara la media (promedio) de todos los valores de una columna con una expresión para obtener un resultado true (verdadero) o false (falso).

Mean "colA" between 80 and 100

Algunos tipos de reglas, como IsUnique y IsComplete ya producen una respuesta booleana.

En la tabla siguiente, se enumeran las expresiones que puede utilizar en las reglas de 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

Palabras clave para NULL, EMPTY y WHITESPACES_ONLY

Para validar si una columna de cadenas contiene una cadena nula, vacía o solo con espacios en blanco, puede utilizar las palabras clave a continuación:

Puede utilizar las palabras clave a continuación para validar si una columna contiene un valor nulo al trabajar con expresiones numéricas o basadas en fechas.

Filtrado con la cláusula Where

Puede filtrar sus datos durante la creación de reglas. Esto resulta útil cuando se quieren aplicar reglas condicionales.

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

El filtro debe especificarse con la palabra clave where, seguida de una instrucción de SparkSQL válida entre comillas ("").

Si desea agregar la cláusula Where a una regla que tiene un umbral, la cláusula Where debe especificarse antes de la condición de umbral.

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

Con esta sintaxis, puede escribir reglas como las siguientes.

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)"

Comprobaremos si la instrucción de SparkSQL proporcionada es válida. Si no es válida, la evaluación de la regla fallará y mostrará el error IllegalArgumentException con el siguiente formato:

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

Comportamiento de la cláusula Where cuando la identificación del registro de errores a nivel de la fila está activada

Con Calidad de datos de AWS Glue, puede identificar registros específicos que fallaron. Al aplicar una cláusula Where a las reglas que admiten resultados a nivel de la fila, etiquetaremos las filas filtradas por la cláusula Where como Passed.

Si prefiere etiquetar por separado las filas filtradas como SKIPPED, puede configurar las siguientes additionalOptions para el trabajo 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 ejemplo, consulte la siguiente regla y el marco de datos:

IsComplete att2 where "att1 = 'a'"

Constantes

En DQDL, puede definir valores constantes y hacer referencia a ellos a lo largo de todo el script. Esto ayuda a evitar problemas relacionados con los límites de tamaño de las consultas, por ejemplo, al trabajar con instrucciones SQL de gran tamaño que podrían superar los límites permitidos. Al asignar estos valores a las constantes, puede simplificar el DQDL y evitar sobrepasar esos límites.

En el siguiente ejemplo, se muestra cómo definir y utilizar una constante:

mySql = "select count(*) from primary"

Rules = [
    CustomSql $mySql between 0 and 100
]

En este ejemplo, la consulta SQL se asigna a la constante mySql, que luego se referencia en la regla mediante el prefijo $.

Etiquetas

Las etiquetas ofrecen una forma eficaz de organizar y analizar los resultados de calidad de los datos. Puede consultar los resultados por etiquetas específicas para identificar reglas fallidas dentro de categorías concretas, contar los resultados de las reglas por equipo o dominio y crear informes específicos para distintas partes interesadas.

Por ejemplo, puede aplicar a todas las reglas relacionadas con el equipo de finanzas una etiqueta "team=finance" y generar un informe personalizado para mostrar métricas de calidad específicas del equipo de finanzas. Puede etiquetar las reglas de alta prioridad con "criticality=high" para priorizar las tareas de remediación. Las etiquetas se pueden crear como parte del DQDL. Puede consultar las etiquetas como parte de los resultados de las reglas, los resultados a nivel de fila y las respuestas de la API, lo que facilita la integración con sus flujos de trabajo existentes de supervisión y generación de informes.

Sintaxis de las etiquetas de DQDL

DQDL admite tanto etiquetas predeterminadas como etiquetas específicas de las reglas. Las etiquetas predeterminadas se definen a nivel del conjunto de reglas y se aplican automáticamente a todas las reglas incluidas en ese conjunto. Las reglas individuales también pueden tener sus propias etiquetas y, dado que las etiquetas se implementan como pares clave-valor, las etiquetas específicas de una regla pueden sustituir a las etiquetas predeterminadas cuando se utiliza la misma clave.

En el siguiente ejemplo, se muestra cómo utilizar etiquetas predeterminadas y específicas de una regla:

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"]
]

Restricciones del etiquetado

Las etiquetas tienen las siguientes restricciones:

Recuperación de etiquetas de DQDL

Puede recuperar las etiquetas de DQDL a partir de los resultados de las reglas, los resultados a nivel de fila y las respuestas de la API.

Resultados de la regla

Las etiquetas de DQDL siempre son visibles en los resultados de las reglas. No se necesita ninguna configuración adicional para habilitarlas.

Resultados a nivel de fila

Las etiquetas de DQDL están desactivadas de forma predeterminada en los resultados a nivel de fila, pero pueden habilitarse mediante AdditionalOptions en EvaluateDataQuality.

En el siguiente ejemplo, se muestra cómo habilitar etiquetas en resultados a nivel de fila:

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"
    }""")
)

Cuando están habilitadas, el marco de datos de resultados a nivel de fila incluye las etiquetas de cada regla en las columnas DataQualityRulesPass, DataQualityRulesFail y DataQualityRulesSkip.

Respuesta de la API

Las etiquetas de DQDL siempre son visibles en las respuestas de la API, en un nuevo campo Labels dentro del objeto RuleResults.

En el siguiente ejemplo, se muestran las etiquetas en una respuesta de la 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"
            }
        }
    ]
}

Reglas dinámicas

Ahora puede crear reglas dinámicas para comparar las métricas actuales generadas por sus reglas con sus valores históricos. Estas comparaciones históricas se habilitan usando el operador last() en las expresiones. Por ejemplo, la regla RowCount > last() se aplicará correctamente cuando el número de filas de la ejecución actual sea superior al recuento de filas anterior más reciente del mismo conjunto de datos. last() utiliza un argumento numérico natural opcional que describe cuántas métricas anteriores se deben tener en cuenta; last(k) donde k >= 1 hará referencia a las últimas métricas k.

Para formar expresiones válidas utilice last(k), donde k > 1 requiera una función de agregación para reducir varios resultados históricos a un solo número. Por ejemplo, RowCount > avg(last(5)) comprobará si el recuento de filas del conjunto de datos actual es estrictamente mayor que el promedio de los últimos cinco recuentos de filas del mismo conjunto de datos. RowCount > last(5) producirá un error, porque el recuento de filas del conjunto de datos actual no se puede comparar de forma significativa con una lista.

Funciones de agregación admitidas:

Ejemplos de expresiones

ColumnCorrelation

DistinctValuesCount

La mayoría de los tipos de reglas con condiciones o umbrales numéricos admiten reglas dinámicas; consulte la tabla dada, Analizadores y reglas, para determinar si las reglas dinámicas son compatibles con su tipo de regla.

Exclusión de las estadísticas de las reglas dinámicas

En ocasiones, tendrá que excluir las estadísticas de datos de los cálculos de las reglas dinámicas. Supongamos que ha efectuado una carga de datos históricos y no quiere que eso afecte a sus promedios. Para ello, abra el trabajo en la ETL de AWS Glue y seleccione la pestaña Calidad de los datos; a continuación, seleccione Estadísticas y seleccione las estadísticas que desee excluir. Podrá ver un gráfico de tendencias junto con una tabla de estadísticas. Seleccione los valores que desee excluir y elija Excluir estadísticas. Ahora las estadísticas que estén excluidas no se incluirán en los cálculos de las reglas dinámicas.

Analizadores

Las reglas de DQDL usan funciones denominadas analizadores para recopilar información sobre los datos. La expresión booleana de una regla hace uso de esta información para determinar si la regla debe funcionar correctamente o no. Por ejemplo, la regla RowCount RowCount > 5 usará un analizador de recuento de filas para descubrir el número de filas del conjunto de datos y compararlo con la expresión > 5, para comprobar si existen más de cinco filas en el conjunto de datos actual.

A veces, en lugar de crear reglas, recomendamos crear analizadores y luego hacer que generen estadísticas que puedan usarse para detectar anomalías. Para estos casos, puede crear analizadores. Los analizadores se diferencian de las reglas en estas formas.

Los analizadores pueden existir de forma independiente sin reglas, por lo que es posible configurarlos rápidamente y crear progresivamente reglas de calidad de datos.

Algunos tipos de reglas se pueden introducir en el bloque Analyzers del conjunto de reglas para ejecutar las reglas necesarias para los analizadores y recopilar información sin comprobar ninguna condición. Algunos analizadores no están asociados a las reglas y solo se pueden introducir en el bloque Analyzers. La siguiente tabla indica si cada elemento se admite como regla o como analizador independiente, junto con información adicional para cada tipo de regla.

Ejemplos de conjunto de reglas con el analizador

El siguiente conjunto de reglas usa:

Los resultados de las métricas del analizador pueden verse en la pestaña Calidad de los datos durante la ejecución del trabajo.

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

Calidad de datos de AWS Glue es compatible con los siguientes analizadores.

Comentarios

Puede utilizar el carácter “#” para agregar un comentario al documento DQDL. DQDL ignorará todo lo que figure a continuación del “#” hasta el final de la línea.

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