Prueba la calidad de los datos

En este documento, se muestra cómo probar el código de tu flujo de trabajo con aserciones de tablas y pruebas de unidades de Dataform.

Antes de comenzar

  1. En la consola de Google Cloud , ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona o crea un repositorio.

  3. Selecciona o crea un espacio de trabajo de desarrollo.

  4. Crea una tabla.

Roles obligatorios

Para obtener los permisos que necesitas para crear aserciones y pruebas unitarias, pídele a tu administrador que te otorgue los siguientes roles de IAM:

  • Editor de Dataform (roles/dataform.editor) en el espacio de trabajo
  • Para sincronizar los metadatos de la aserción con Knowledge Catalog, debes tener el rol de Editor de Dataplex Catalog (roles/dataplex.catalogEditor) en el proyecto o el grupo de entradas @bigquery.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Datos de prueba con aserciones

Una aserción es una consulta de prueba de calidad de los datos que encuentra filas que incumplen una o más condiciones especificadas en la consulta. Si la consulta devuelve filas, la aserción falla. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo y te avisa si alguna falla.

Dataform crea automáticamente vistas en BigQuery que contienen los resultados de las consultas de aserción compiladas. Como se configuró en el archivo de configuración del flujo de trabajo, Dataform crea estas vistas en un esquema de aserciones en el que puedes inspeccionar los resultados de las aserciones.

Por ejemplo, para el esquema dataform_assertions predeterminado, Dataform crea una vista en BigQuery con el siguiente formato: dataform_assertions.assertion_name.

Puedes crear aserciones para todos los tipos de tablas de Dataform: tablas, tablas incrementales, vistas y vistas materializadas.

Puedes crear aserciones de las siguientes maneras:

Crea aserciones integradas

Puedes agregar aserciones integradas de Dataform al bloque config de una tabla. Dataform ejecuta estas aserciones después de la creación de la tabla. Después de que Dataform cree la tabla, puedes ver si la aserción pasó en la pestaña Registros de ejecución del flujo de trabajo de tu espacio de trabajo.

Puedes crear las siguientes aserciones en el bloque config de una tabla:

  • nonNull

    Esta condición afirma que las columnas especificadas no son nulas en todas las filas de la tabla. Esta condición se usa para las columnas que nunca pueden ser nulas.

    En la siguiente muestra de código, se muestra una aserción nonNull en el bloque config de una tabla:

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...

  • rowConditions

    Esta condición afirma que todas las filas de la tabla siguen la lógica personalizada que defines. Cada condición de fila es una expresión SQL personalizada, y cada fila de la tabla se evalúa en función de cada condición de fila. La aserción falla si alguna fila de la tabla genera false.

    En la siguiente muestra de código, se muestra una aserción rowConditions personalizada en el bloque config de una tabla incremental:

config {
  type: "incremental",
  assertions: {
    rowConditions: [
      'signup_date is null or signup_date > "2022-08-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

  • uniqueKey

    Esta condición afirma que, en una columna especificada, ninguna fila de la tabla tiene el mismo valor.

    En el siguiente muestra de código, se muestra una aserción uniqueKey en el bloque config de una vista:

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...

  • uniqueKeys

    Esta condición afirma que, en las columnas especificadas, ninguna fila de la tabla tiene el mismo valor. La aserción falla si hay más de una fila en la tabla con los mismos valores para todas las columnas especificadas.

    En el siguiente muestra de código, se muestra una aserción uniqueKeys en el bloque config de una tabla:

config {
  type: "table",
  assertions: {
    uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
  }
}
SELECT ...

Agrega aserciones al bloque config

Para agregar aserciones al bloque de configuración de una tabla, sigue estos pasos:

  1. En tu lugar de trabajo de desarrollo, en el panel Archivos, selecciona un archivo SQLX de definición de tabla.
  2. En el bloque config del archivo de la tabla, ingresa assertions: {}.
  3. Dentro de assertions: {}, agrega tus aserciones.
  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestran las condiciones agregadas en el bloque config:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
    rowConditions: [
      'signup_date is null or signup_date > "2019-01-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

Crea aserciones manuales con SQLX

Las aserciones manuales son consultas en SQL que escribes en un archivo SQLX dedicado. Una consulta en SQL de aserción manual debe devolver cero filas. Si la consulta devuelve filas cuando se ejecuta, la aserción falla.

Para agregar aserciones manuales en un archivo .sqlx nuevo, sigue estos pasos:

  1. En el panel Archivos, junto a definitions/, haz clic en el menú Más.
  2. Haz clic en Crear archivo.

  3. En el campo Agregar una ruta de archivo, ingresa el nombre del archivo seguido de .sqlx. Por ejemplo, definitions/custom_assertion.sqlx.

    Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

  4. Haz clic en Crear archivo.

  5. En el panel Archivos, haz clic en el archivo nuevo.

  6. En el archivo, ingresa lo siguiente:

    config {
  type: "assertion"
}

  7. Debajo del bloque config, escribe tu consulta en SQL o varias consultas.

  8. Opcional: Haz clic en Formato.

En el siguiente muestra de código, se muestra una aserción manual en un archivo SQLX que confirma que los campos A, B y c nunca son NULL en sometable:

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("sometable")}
WHERE
  a IS NULL
  OR b IS NULL
  OR c IS NULL

Prueba la calidad de los datos con pruebas de unidades

Una prueba de unidades es una prueba de calidad de los datos, definida en un archivo .sqlx dedicado, que simula todas las dependencias de la acción del flujo de trabajo probado y proporciona los resultados esperados. Puedes usar pruebas de unidades para probar las acciones de Dataform con entradas simuladas controladas y verificar si el código de acción controla correctamente los casos extremos, los valores nulos, las agregaciones, las expresiones regulares y la lógica condicional.

Las simulaciones para las dependencias de acciones, como las tablas predecesoras, las vistas o las declaraciones sin procesar a las que se hace referencia en la función ${ref()}, se definen en los bloques input. Cada bloque input hace referencia a una dependencia por su nombre y contiene una consulta en SQL que define las filas simuladas. Por lo general, esta consulta es una serie de instrucciones SELECT combinadas con UNION ALL. Los resultados esperados son consultas en SQL que representan los resultados de ejecutar las entradas especificadas en la instrucción de SQL de la acción del flujo de trabajo.

Dataform ejecuta pruebas de unidades fila por fila y compara el resultado real de ejecutar la lógica de SQL de una acción del flujo de trabajo con datos simulados y un conjunto de resultados esperados.

Las pruebas de unidades se resuelven en los siguientes estados:

  • SUCCESS: La prueba se aprobó. Los resultados reales coinciden con los esperados.
  • FAILURE: No se pudo realizar la prueba. Los resultados reales no coinciden con los esperados.

Limitaciones

Las pruebas de unidades de Dataform están disponibles con las siguientes limitaciones:

  • Las pruebas de unidades están disponibles en la versión 3.0.56 y posteriores de Dataform Core.
  • El tamaño máximo de los datos de entrada en una prueba unitaria es de 100 filas por entrada.

Crea pruebas de unidades

Almacena los archivos .sqlx para las pruebas de unidades en el directorio definitions/. Para crear un archivo .sqlx de prueba unitaria nuevo en el directorio definitions/, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. En el panel Archivos, junto a definitions/, haz clic en el menú Más.

  5. Haz clic en Crear archivo.

  6. En el panel Crear un archivo nuevo, haz lo siguiente:

    1. En el campo Agregar una ruta de archivo, después de definitions/, ingresa el nombre del archivo seguido de _test.sqlx. Por ejemplo, definitions/customer_spend_test.sqlx

      Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

    2. Haz clic en Crear archivo.

  7. En el archivo de prueba, agrega el siguiente bloque config:

    config {
  type: "test",
  dataset: "ACTION_NAME"
}

    Reemplaza ACTION_NAME por el nombre de la acción que valida esta prueba.

  8. Para simular la acción probada, agrega un bloque input para cada dependencia de la acción y escribe una consulta en SQL que pruebe esa dependencia con el siguiente formato:

    input "DEPENDENCY_NAME" {
SELECT ...
SELECT ...
}

    Reemplaza DEPENDENCY_NAME por el nombre de la dependencia de acción probada que simula esta entrada.

  9. Debajo de los bloques input, escribe consultas en SQL estándar que representen las filas de salida esperadas con el siguiente formato:

    -- Expected Output
SELECT ...
SELECT ...

Las consultas de salida esperadas solo deben devolver las filas y columnas que la acción probada debería producir con las entradas simuladas.

En el siguiente muestra de código, se muestra la acción del flujo de trabajo customer_spend.sqlx:

config {
type: "table",
name: "customer_spend"
}

SELECT
  c.customer_id,
  c.name,
  SUM(o.amount) AS total_completed_amount
FROM
  ${ref("source_customers")} c
  JOIN
  ${ref("source_orders")} o
  ON c.customer_id = o.customer_id
WHERE
  o.status = 'COMPLETED'
GROUP BY
  1, 2

El siguiente muestra de código muestra la prueba de unidades customer_spend_test.sqlx que simula las dependencias de la acción customer_spend.sqlx y define los resultados esperados para las simulaciones:

config {
  type: "test",
  dataset: "customer_spend"
}

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, 'Bob' AS name UNION ALL
  SELECT 103 AS customer_id, 'Charlie' AS name
}

input "source_orders" {
  -- Alice has one completed and one pending order
  SELECT 1 AS order_id, 101 AS customer_id, 'COMPLETED' AS status, 100.0 AS amount UNION ALL
  SELECT 2 AS order_id, 101 AS customer_id, 'PENDING' AS status, 50.0 AS amount UNION ALL
  -- Bob has one completed order
  SELECT 3 AS order_id, 102 AS customer_id, 'COMPLETED' AS status, 250.0 AS amount UNION ALL
  -- Charlie has no orders
  SELECT 4 AS order_id, 999 AS customer_id, 'COMPLETED' AS status, 10.0 AS amount
}

-- Expected Output
SELECT 101 AS customer_id, 'Alice' AS name, 100.0 AS total_completed_amount UNION ALL
SELECT 102 AS customer_id, 'Bob' AS name, 250.0 AS total_completed_amount

Ejecutar pruebas de unidades

Para ejecutar pruebas de unidades, sigue estos pasos:

Console

  1. En la consola de Google Cloud , ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. Haz clic en Iniciar ejecución  > Ejecutar acciones.

  5. En el panel Ejecutar, en la sección Modo de ejecución, selecciona Pruebas de unidades.

  6. Selecciona una de las siguientes opciones:

    • Seleccionar pruebas de unidades: Ejecuta las pruebas de unidades que seleccionas de forma manual.
    • Seleccionar pruebas de unidades etiquetadas: Ejecuta pruebas de unidades con una etiqueta seleccionada.
    • All unit tests: Ejecuta todas las pruebas de unidades en el espacio de trabajo.

  7. Opcional: En las secciones Opciones de ejecución, selecciona la casilla de verificación Ejecutar como trabajo interactivo con alta prioridad para ejecutar pruebas unitarias de inmediato y priorizar la velocidad de ejecución.

    Si no seleccionas la casilla de verificación Ejecutar como trabajo interactivo con alta prioridad, Dataform ejecutará pruebas unitarias con recursos por lotes de forma predeterminada, lo que priorizará el ahorro en los costos de procesamiento.

  8. Haz clic en Iniciar ejecución.

API

Para ejecutar pruebas de unidades de forma programática, crea una invocación de flujo de trabajo con el método WorkflowInvocations.create y establece los siguientes parámetros de ejecución de prueba de unidades en el objeto invocationConfig:

"executionMode": "UNIT_TESTS_ONLY"
Este parámetro, establecido en "UNIT_TESTS_ONLY", activa la ejecución de las pruebas de unidades definidas en el repositorio.
Opcional: "queryPriority": "INTERACTIVE"
Cuando este parámetro se establece en "INTERACTIVE", Dataform ejecuta las consultas de inmediato. Si no se configura, Dataform ejecuta pruebas de unidades con la prioridad de consulta por lotes predeterminada.
Opcional: "includedTargets": []
Este parámetro te permite especificar pruebas de unidades para que Dataform ejecute solo estas pruebas.
Opcional: "includedTags": []
Este parámetro te permite especificar etiquetas para que Dataform ejecute solo las pruebas de unidades etiquetadas con esas etiquetas.

En el siguiente muestra de código, se muestra el cuerpo de una invocación de flujo de trabajo que ejecuta todas las pruebas de unidades definidas en el repositorio my-repo con la prioridad de consulta por lotes predeterminada:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY"
  }
}

En el siguiente muestra de código, se muestra el cuerpo de una invocación de flujo de trabajo que ejecuta solo la prueba unitaria my-test con la prioridad de consulta interactiva:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTargets": [
      {
        "database": "my-project",
        "schema": "my-dataset",
        "name": "my-test"
      }
    ]
  }
}

En el siguiente muestra de código, se muestra el cuerpo de una invocación de flujo de trabajo que ejecuta pruebas unitarias en el repositorio my-repo etiquetadas con test-tag-1 o test-tag-2:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTags": [
      "test-tag-1",
      "test-tag-2"
    ]
  }
}

Inspecciona los resultados de las pruebas de unidades

Puedes inspeccionar las diferencias entre los guiones esperados y reales de una prueba unitaria en el Gráfico compilado o en Ejecuciones.

Gráfico compilado

Para ver las secuencias de comandos reales y esperadas de una prueba de unidades en el gráfico compilado de las acciones del flujo de trabajo, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. Opcional: Para ver las pruebas de unidades vinculadas a las acciones que prueban, en lugar de verlas como nodos independientes del gráfico, establece el parámetro de configuración includeTestsInCompiledGraph en true en el archivo workflow_settings.yaml:

    1. Selecciona el archivo workflow_settings.yaml.
    2. Agrega el siguiente código:
    includeTestsInCompiledGraph: true

  5. Haz clic en Gráfico compilado.

  6. En el gráfico compilado, selecciona una prueba unitaria y, luego, haz clic en Consulta.

  7. Compara la secuencia de comandos de SQL real y la secuencia de comandos de SQL esperada.

Ejecuciones

  1. En la consola de Google Cloud , ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. Haz clic en Ejecuciones y, luego, en Ver detalles junto a la prueba unitaria seleccionada.

  5. Compara la consulta de resultados reales y la consulta de resultados esperados.

Prácticas recomendadas para las pruebas unitarias

Mantén pequeños los conjuntos de datos de simulación
Mantén los datos de entrada simulados en menos de 10 filas para una compilación más rápida y una depuración más sencilla.
Cómo especificar un orden de fila explícito
Siempre agrega una cláusula ORDER BY a la consulta de acción y a la consulta de salida esperada para garantizar un orden determinístico de las filas durante la evaluación.
Convierte explícitamente las columnas en tus instrucciones simuladas
Convertir de forma explícita las columnas en tus instrucciones simuladas (por ejemplo, con CAST(100 AS INT64)) mantiene la rigidez del tipo y evita errores de compilación.
Incluye casos de prueba con valores NULL o faltantes
Incluir casos de prueba con NULL o valores faltantes en tus consultas simuladas de entrada garantiza que tus instrucciones COALESCE, operaciones de cadenas y criterios de filtro controlen de forma segura los datos de producción incompletos o nulos.

En el siguiente muestra de código, se muestra un caso de prueba de NULL:

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, NULL AS name -- Test null handling
}

¿Qué sigue?