Prueba tablas con aserciones

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

Información acerca de las 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 muestra alguna fila, la aserción falla. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo de SQL y te alerta 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 de tu 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:

Antes de comenzar

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

    Ve a la página Dataform

  2. Selecciona o crea un repositorio.

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

  4. Define una tabla.

Roles obligatorios

Para obtener los permisos que necesitas para crear aserciones, pídele a tu administrador que te otorgue el rol de IAM de editor de Dataform (roles/dataform.editor) en los espacios de trabajo. 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 mediante roles personalizados o cualquier otro rol predefinido.

Crea aserciones integradas

Puedes agregar aserciones de Dataform integradas 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 se pasó en la pestaña Registros de ejecución de 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 columnas que nunca pueden ser nulos.

    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 muestra 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 la 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 la 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 Files, selecciona un archivo SQLX de definición de tabla.
  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 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 SQL que escribes en un archivo SQLX dedicado. Una consulta de 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 nuevo archivo SQLX, 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 Files, haz clic en el archivo nuevo.

  6. En el archivo, ingresa lo siguiente:

    config {
  type: "assertion"
}

  7. Debajo del bloque config, escribe una o varias consultas SQL.

  8. Opcional: Haz clic en Formato.

En el siguiente ejemplo 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

Establece aserciones como dependencias

Cuando la acción del flujo de trabajo B depende de la acción del flujo de trabajo A 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 la acción A, debes establecer las aserciones de la acción A como dependencias de la acción B.

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

Establece las aserciones seleccionadas como dependencias

Puedes establecer manualmente las aserciones seleccionadas como dependencias agregándolas 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 deseas que la acción B dependa solo de las aserciones seleccionadas de la acción A, puedes agregar esas aserciones seleccionadas al bloque config de la acción B.

Puedes establecer manualmente las aserciones seleccionadas como dependencias para todos los tipos de acciones, excepto las declaraciones de fuentes de datos.

Establece 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 deseas que la acción C dependa de las aserciones de la 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
Establece aserciones de todas las acciones de dependencia como dependencias

Puedes configurar el parámetro dependOnDependencyAssertions para establecer 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 configurar 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 el parámetro dependOnDependencyAssertions y los parámetros includeDependentAssertions en un solo archivo, el parámetro includeDependentAssertions tiene prioridad. Por ejemplo, si estableces dependOnDependencyAssertions en true, pero también estableces 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 muestran 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.

Establece las aserciones seleccionadas como dependencias

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

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

  1. En el panel Files de tu lugar de trabajo de desarrollo, 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. Dentro de dependencies: [ "" ], ingresa el nombre de la aserción de acción o el nombre del archivo de la aserción manual que deseas establecer como una 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 de 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 de 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 de 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 de 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 de flujo de trabajo: table, view o operations.
    • MANUAL_ASSERTION_NAME 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, que se define en el conjunto de datos dataform:

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

En la 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 afirmaciones 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 aprueben todas las aserciones directas de una acción de dependencia seleccionada, establece el parámetro includeDependentAssertions en 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 establecer todas las aserciones de una acción de dependencia seleccionada como dependencias, sigue estos pasos:

  1. En el panel Files de tu lugar de trabajo de desarrollo, 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 de flujo de trabajo: table, view o operations.
    • DEPENDENCY_ACTION_NAME: Es el nombre de la acción de dependencia cuyas aserciones 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 de flujo de trabajo: table, view o operations.
    • DEPENDENCY_ACTION_NAME: Es el nombre de la acción de dependencia cuyas aserciones deseas establecer como dependencias de la acción editada.

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra 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 afirmaciones directas de tableB como dependencias a tableC durante la compilación.

Establece aserciones de todas las acciones de dependencia como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se aprueben todas las aserciones directas de todas las acciones de dependencia, establece el parámetro dependOnDependencyAssertions en 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 el parámetro dependOnDependencyAssertions y los parámetros includeDependentAssertions en un solo archivo, el parámetro includeDependentAssertions tiene prioridad para la acción de dependencia para la que se configuró.

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

  1. En el panel Files de tu lugar de trabajo de desarrollo, 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 por el tipo de acción del flujo de trabajo. Los valores admitidos son table, view y operations.

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra sometableE que depende de sometableA, sometabletableB, sometableC y sometableD, y 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 afirmaciones directas de sometableA, sometableB, sometableC y sometableD como dependencias a sometableE durante la compilación.

¿Qué sigue?