Prueba tablas con aserciones

En este documento, se muestra cómo usar Dataform Core para crear aserciones de tablas de Dataform y probar el código de tu flujo de trabajo.

Acerca de las aserciones

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

Dataform crea automáticamente vistas en BigQuery que contienen los resultados de las consultas de aserción compiladas. Como se configura 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 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:

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 lugar de trabajo de desarrollo.

  4. Define una tabla.

Funciones obligatorias

Si deseas obtener los permisos que necesitas para crear aserciones, pídele a tu administrador que te otorgue el rol de IAM Editor de Dataform (roles/dataform.editor) en los lugares de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios a través de funciones personalizadas o, también, otras funciones predefinidas.

Cómo crear 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 publique la tabla, puedes inspeccionar la aserción.

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

  • nonNull

    Esta condición declara 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 observa 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 confirma que todas las filas de la tabla siguen la lógica personalizada que definas. Cada condición de fila es una expresión de 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 infringe alguna condición de la fila.

    En la siguiente muestra de código, aparece 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 declara que, en una columna especificada, ninguna fila de la tabla tiene el mismo valor.

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

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

  • uniqueKeys

    Esta condición declara 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 la siguiente muestra de código, se observa 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 el lugar de trabajo de desarrollo, en el panel Files, selecciona un archivo SQLX de definición de tablas.
  2. En el bloque config del archivo de tabla, ingresa assertions: {}.
  3. Dentro de assertions: {}, agrega tus aserciones.
  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observan las condiciones que se agregaron 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 mostrar cero filas. Si la consulta muestra filas cuando se ejecuta, la aserción falla.

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

  1. En el panel Files, junto a definitions/, haz clic en el menú More.
  2. Haz clic en Crear archivo.

  3. En el campo Agregar una ruta de acceso al 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 Files, 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 la siguiente muestra de código, aparece una aserción manual en un archivo SQLX que indica 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

Cómo configurar aserciones como dependencias

Cuando la acción B del flujo de trabajo depende de la acción A del flujo de trabajo que tiene aserciones, la falla de las aserciones de la acción A no impide que Dataform ejecute la acción B. Para ejecutar la acción B solo si se aprueban las aserciones de acción A, debes establecer las aserciones de acción A como dependencias de la acción B.

Puedes establecer aserciones como dependencias de una acción seleccionada de las siguientes maneras:

Configura las aserciones seleccionadas como dependencias

Para configurar manualmente las aserciones seleccionadas como dependencias, agrégalas a dependencies: [ "" ] en el bloque config de la acción editada.

Por ejemplo, si la acción B depende de la acción A y quieres que la acción B dependa solo de las aserciones de acción seleccionadas A, puedes agregar esas aserciones seleccionadas al bloque de acción config B.

Puedes configurar de forma manual las aserciones seleccionadas como dependencias para todos los tipos de acción, excepto las declaraciones de fuentes de datos.

Configura aserciones de una acción de dependencia seleccionada como dependencias

Puedes configurar el parámetro includeDependentAssertions para establecer automáticamente todas las aserciones directas de una acción de flujo de trabajo de dependencia seleccionada como dependencias de la acción editada. Dataform agrega estas aserciones como dependencias durante cada compilación de la acción para garantizar que las dependencias estén actualizadas si cambian las aserciones de la acción de dependencia.

Por ejemplo, si la acción C depende de las acciones A y B, pero solo quieres que la acción C dependa de las aserciones de acción A, puedes editar la acción C y establecer el parámetro includeDependentAssertions para configurar automáticamente todas las aserciones de la acción A como dependencias de la acción C.

Puedes configurar el parámetro includeDependentAssertions para acciones de los siguientes tipos:

  • table
  • view
  • operations
Configura aserciones de todas las acciones de dependencia como dependencias

Puedes establecer el parámetro dependOnDependencyAssertions para configurar automáticamente todas las aserciones directas de todas las acciones de dependencia de la acción editada como dependencias adicionales de la acción editada. Dataform agrega estas aserciones como dependencias durante cada compilación de la acción para garantizar que las dependencias estén actualizadas si cambian las aserciones de la acción de dependencia.

Por ejemplo, si la acción C depende de las acciones A y B, puedes editar la acción C y establecer el parámetro dependOnDependencyAssertions para establecer automáticamente todas las aserciones de las acciones A y B como dependencias de la acción C.

Puedes configurar el parámetro dependOnDependencyAssertions para acciones de los siguientes tipos:

  • table
  • view
  • operations

Cuando configuras los parámetros dependOnDependencyAssertions y includeDependentAssertions en un solo archivo, el parámetro includeDependentAssertions tiene prioridad. Por ejemplo, si configuras dependOnDependencyAssertions como true, pero también includeDependentAssertions en false para una acción de dependencia seleccionada, Dataform no agregará aserciones de esa acción a las dependencias.

En la siguiente muestra de código, se observan los parámetros dependOnDependencyAssertions y includeDependentAssertions establecidos en el mismo archivo de definición de tablas:

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

En la muestra de código anterior, Dataform agrega todas las aserciones directas de actionA y actionC a las dependencias de tableName durante la compilación.

Configura las aserciones seleccionadas como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se aprueban las aserciones seleccionadas, puedes agregar la aserción seleccionada a dependencies: [ "" ] en el bloque config de la acción editada.

Para configurar una aserción seleccionada como una dependencia de una acción de flujo de trabajo seleccionada, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.
  3. En el bloque config del archivo de acción, ingresa dependencies: [ "" ].

  4. En dependencies: [ "" ], ingresa el nombre de la aserción de acción o el nombre de archivo de la aserción manual que deseas establecer como dependencia en uno de los siguientes formatos:

    nonNull

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • ACTION_DATASET_NAME: Es el nombre del conjunto de datos en el que se define la acción. El conjunto de datos predeterminado se define en el archivo de configuración del flujo de trabajo.
    • ACTION_NAME: Es el nombre de la acción en la que se define la aserción.

    rowConditions

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: Es el nombre del conjunto de datos en el que se define la acción. El conjunto de datos predeterminado se define en el archivo de configuración del flujo de trabajo.
    • ACTION_NAME: Es el nombre de la acción en la que se define la aserción.

    uniqueKey

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: Es el nombre del conjunto de datos en el que se define la tabla. El conjunto de datos predeterminado se define en el archivo de configuración del flujo de trabajo.
    • ACTION_NAME: Es el nombre de la tabla en la que se define la aserción.
    • INDEX: Es el índice del array de claves definido en la aserción uniqueKey que deseas agregar como dependencia. Por ejemplo, 0 o 1. Si solo se define un array de claves en la aserción, el índice es 0.

    uniqueKeys

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: Es el nombre del conjunto de datos en el que se define la tabla. El conjunto de datos predeterminado se define en el archivo de configuración del flujo de trabajo.
    • ACTION_NAME: Es el nombre de la tabla en la que se define la aserción.
    • INDEX: Es el índice del array de claves definido en la aserción uniqueKeys que deseas agregar como dependencia, por ejemplo, 0 o 1. Si solo se define un array de claves en la aserción, el índice es 0.

    aserción manual

    config {
  type: "ACTION_TYPE",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • MANUAL_ASSERTION_NAME es el nombre de la aserción manual.

  5. Para agregar otra aserción como dependencia a la tabla editada, repite el Paso 4.

  6. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestran las aserciones agregadas a la tabla A, definidas en el conjunto de datos dataform:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

En el siguiente muestra de código, se muestran las aserciones de la tabla A agregadas como dependencias a la tabla B:

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

En la siguiente muestra de código, se muestra una aserción manual definida en el archivo manualAssertion.sqlx, que se agrega como dependencia a una vista:

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

En la siguiente muestra de código, se muestra el archivo manual_assertion y las aserciones de la tabla sometable agregadas como dependencias a una tabla:

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

Cómo establecer aserciones de una acción seleccionada como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se pasen todas las aserciones directas de una acción de dependencia seleccionada, establece el parámetro includeDependentAssertions como true en la acción editada. Dataform agrega automáticamente aserciones directas de la acción de dependencia seleccionada a las dependencias durante la compilación. El valor predeterminado es false.

Para configurar todas las aserciones de una acción de dependencia seleccionada como dependencias, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.

  3. En el archivo, configura el parámetro includeDependentAssertions como true de una de las siguientes maneras:

    En el bloque config

    config {
type: "ACTION_TYPE",
dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • DEPENDENCY_ACTION_NAME: Es el nombre de la acción de dependencia que las aserciones que deseas establecer como dependencias de la acción editada.

    En la sentencia SELECT

      config { type: "ACTION_TYPE" }

  SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}

    Reemplaza lo siguiente:

    • ACTION_TYPE: Es el tipo de acción del flujo de trabajo: table, view o operations.
    • DEPENDENCY_ACTION_NAME: Es el nombre de la acción de dependencia que las aserciones que deseas establecer como dependencias de la acción editada.

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observa tableC que depende de viewA, tableB y todas las aserciones de tableB:

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

En la muestra de código anterior, Dataform agrega automáticamente todas las aserciones directas de tableB como dependencias a tableC durante la compilación.

Cómo establecer aserciones de todas las acciones de dependencia como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se pasen todas las aserciones directas de todas las acciones de dependencia, configura el parámetro dependOnDependencyAssertions como true en la acción editada. Dataform agrega automáticamente aserciones directas de acciones de dependencia como dependencias durante la compilación. El valor predeterminado es false.

Cuando configuras los parámetros dependOnDependencyAssertions y includeDependentAssertions en un solo archivo, el parámetro includeDependentAssertions tiene prioridad para la acción de dependencia para la que se configuró.

Para configurar todas las aserciones de una acción de dependencia seleccionada como dependencias, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.

  3. En el archivo, configura el parámetro dependOnDependencyAssertions como true en el siguiente formato:

    config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}

    Reemplaza ACTION_TYPE: El tipo de la acción del flujo de trabajo. Los valores admitidos incluyen table, view y operations.

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observa sometableE que depende de sometableA, sometabletableB, sometableC y sometableD, además de todas las aserciones directas de las tablas de dependencias:

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

En la muestra de código anterior, Dataform agrega automáticamente todas las aserciones directas de sometableA, sometableB, sometableC y sometableD como dependencias a sometableE durante la compilación.

¿Qué sigue?