Cómo establecer dependencias

En este documento, se muestra cómo definir la relación entre los objetos de tu flujo de trabajo en Dataform declarando dependencias.

Puedes definir una relación de dependencia entre objetos de un flujo de trabajo. En una relación de dependencia, la ejecución del objeto dependiente depende de la ejecución del objeto de dependencia. Esto significa que Dataform ejecuta el elemento dependiente después de la dependencia. Para definir la relación, debes declarar dependencias dentro del archivo de definición de SQLX del objeto dependiente.

Las declaraciones de dependencia conforman un árbol de dependencias de tu flujo de trabajo que determina el orden en el que Dataform ejecuta las acciones de tu flujo de trabajo.

Puedes definir la relación de dependencia entre las siguientes acciones del flujo de trabajo:

Declaraciones de fuentes de datos
Declaraciones de fuentes de datos de BigQuery que te permiten hacer referencia a estas fuentes de datos en las definiciones de tablas de Dataform y las operaciones de SQL Puedes establecer una declaración de fuente de datos como una dependencia, pero no como un elemento dependiente.
Tablas
Tablas que creas en Dataform en función de las fuentes de datos declaradas o de otras tablas de tu flujo de trabajo. Dataform admite los siguientes tipos de tablas: tabla, tabla incremental, vista y vista materializada. Puedes establecer una tabla como dependencia y como dependiente.
Operaciones de SQL personalizadas
Instrucciones SQL que Dataform ejecuta en BigQuery tal como están, sin modificaciones. Puedes establecer una operación de SQL personalizada definida en un archivo type: operations como dependencia y como elemento dependiente. Para declarar una operación SQL personalizada como dependencia en la función ref, debes establecer la propiedad hasOutput en true en el archivo de definición SQLX de la operación SQL personalizada.
Aserciones
Consultas de prueba de calidad de los datos que puedes usar para probar los datos de la tabla. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo y te avisa si alguna falla. Puedes establecer una aserción definida en un archivo type: assertion como una dependencia y como un elemento dependiente declarando dependencias en el bloque config.

Puedes definir la relación de dependencia de las siguientes maneras:

Antes de comenzar

  1. Crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.
  2. Opcional: Declara una fuente de datos.
  3. Crea al menos dos acciones de flujo de trabajo: tablas, aseveraciones, declaraciones de fuentes de datos o operaciones.

Roles obligatorios

Para obtener los permisos que necesitas para declarar dependencias para tablas, aserciones, declaraciones de fuentes de datos y operaciones de SQL personalizadas, 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.

Declarar una dependencia como argumento de la función ref

Para hacer referencia a una dependencia y declararla automáticamente en una sentencia SELECT, agrega la dependencia como un argumento de la función ref.

La función ref es una función integrada de Dataform Core que te permite hacer referencia a cualquier tabla, declaración de fuente de datos o operación de SQL personalizada y depender automáticamente de ellos con la propiedad hasOutput establecida en true en tu flujo de trabajo.

Para obtener más información sobre la función ref, consulta la referencia de los métodos de contexto principales de Dataform.

Para obtener más información sobre el uso de la función ref en una definición de tabla, consulta Acerca de las definiciones de tabla.

En el siguiente muestra de código, se muestra la declaración de la fuente de datos source_data agregada como un argumento de la función ref en el archivo de definición incremental_table.sqlx SQLX de una tabla incremental:

// filename is incremental_table.sqlx

config { type: "incremental" }

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

En la muestra de código anterior, source_data se declara automáticamente como una dependencia de incremental_table.

En el siguiente muestra de código, se muestra el archivo SQLX de definición de la tabla some_table agregado como argumento de la función ref en el archivo de definición de SQLX custom_assertion.sqlx de una aserción:

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

En la muestra de código anterior, some_table se declara automáticamente como una dependencia de custom_assertion. Durante la ejecución, Dataform primero ejecuta some_table y, luego, ejecuta custom_assertion una vez que se crea some_table.

Cómo declarar dependencias en el bloque config

Para declarar dependencias a las que no se hace referencia en la definición de la instrucción de SQL del elemento dependiente, pero que deben ejecutarse antes de la tabla, la aserción o la operación de SQL personalizada, sigue estos pasos:

  1. En el espacio de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de la tabla, la aserción o la operación SQL personalizada que deseas editar.

  3. En el bloque config del archivo, ingresa el siguiente fragmento de código:

    dependencies: [ "DEPENDENCY", ]

    Reemplaza DEPENDENCY por el destino de la cadena, por ejemplo, el nombre de archivo de la acción que deseas agregar como dependencia. Puedes ingresar varios objetivos separados por comas.

  4. Opcional: Haz clic en Formato.

En el siguiente muestra de código, se muestran la tabla some_table y la aserción some_assertion agregadas como dependencias al bloque config de un archivo de definición de tabla:

config { dependencies: [ "some_table", "some_assertion" ] }

Cómo establecer aserciones como dependencias

Cuando la acción de flujo de trabajo B depende de la acción de 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 establecer 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 la línea 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 solo dependa 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.

Cómo establecer las 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 verificar 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 la acción A, puedes editar la acción C y establecer el parámetro includeDependentAssertions para establecer automáticamente todas las aserciones de la acción A como dependencias de la acción C.

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

  • table
  • view
  • operations
Establece las 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 verificar 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 establecer el parámetro dependOnDependencyAssertions para las 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á las 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 tabla:

// 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 aprueban las aserciones seleccionadas, puedes agregar la aserción seleccionada a la línea dependencies: [ "" ] en el bloque config de la acción editada.

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

  1. En el espacio 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. Dentro de 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 el 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 el siguiente muestra de código, se muestra una aserción manual que se define en el archivo manualAssertion.sqlx y se agrega como dependencia a una vista:

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

En el siguiente muestra de código, se muestran 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 ...

Establece las aserciones de una acción seleccionada como dependencias

Para ejecutar una acción del flujo de trabajo solo cuando se aprueban 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 las 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 espacio 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 con 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 con las aserciones que deseas establecer como dependencias de la acción editada.

  4. Opcional: Haz clic en Formato.

En el 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 el muestra de código anterior, Dataform agrega automáticamente todas las aserciones directas de tableB como dependencias de tableC durante la compilación.

Establece las aserciones de todas las acciones de dependencia como dependencias

Para ejecutar una acción del flujo de trabajo solo cuando todas las aserciones directas de todas las acciones de dependencia se aprueban, establece el parámetro dependOnDependencyAssertions en true en la acción editada. Dataform agrega automáticamente las aserciones directas de las 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 espacio 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 con el siguiente formato:

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

    Reemplaza ACTION_TYPE: Es 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, sometableD y todas las aserciones directas de las tablas de dependencia:

// filename is sometableE.sqlx

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

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

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

Haz referencia a una tabla con un nombre de tabla anulado

  • Para hacer referencia a una tabla con un nombre anulado, en la función ref, ingresa el nombre anulado que se configuró en name: "".

La siguiente muestra de código hace referencia a una tabla con un nombre anulado a overridden_name:

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

Para obtener más información sobre cómo anular los nombres de las tablas, consulta Cómo anular la configuración de la tabla.

¿Qué sigue?