Definir dependencias

En este documento se explica 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 los 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 la dependencia después de la dependencia. Para definir la relación, debes declarar las dependencias en el archivo de definición SQLX del objeto dependiente.

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

Puede definir la relación de dependencia entre las siguientes acciones de 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 definiciones de tablas y operaciones SQL de Dataform. Puedes definir una declaración de fuente de datos como dependencia, pero no como elemento dependiente.
Tablas
Tablas que creas en Dataform a partir de las fuentes de datos declaradas u otras tablas de tu flujo de trabajo. Dataform admite los siguientes tipos de tablas: tabla, tabla incremental, vista y vista materializada. Puedes definir una tabla como dependencia y como elemento dependiente.
Operaciones de SQL personalizadas
Instrucciones SQL que Dataform ejecuta en BigQuery tal cual, sin modificaciones. Puedes definir una operación 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 asignar el valor true a la propiedad hasOutput en el archivo de definición SQLX de la operación SQL personalizada.
Aserciones
Consultas de prueba de calidad de los datos que puede usar para probar los datos de las tablas. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo y te avisa si falla alguna. Puedes definir una aserción definida en un archivo type: assertion como dependencia y como elemento dependiente declarando dependencias en el bloque config.

Puede definir la relación de dependencia de las siguientes formas:

Antes de empezar

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

Roles obligatorios

Para obtener los permisos que necesitas para declarar dependencias de tablas, aserciones, declaraciones de fuentes de datos y operaciones SQL personalizadas, pide a tu administrador que te conceda el rol de editor de Dataform (roles/dataform.editor) de gestión de identidades y accesos en los espacios de trabajo. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Declarar una dependencia como argumento de la función ref

Para hacer referencia a una dependencia y declararla automáticamente en una instrucción SELECT, añade la dependencia como 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 u operación de SQL personalizada y depender automáticamente de ella con la propiedad hasOutput definida como true en tu flujo de trabajo.

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

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

En el siguiente ejemplo de código se muestra la declaración de la fuente de datos source_data añadida como 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 el ejemplo de código anterior, source_data se declara automáticamente como dependencia de incremental_table.

En el siguiente ejemplo de código se muestra el archivo SQLX de definición de tabla some_table añadido como argumento de la función ref en el archivo de definición 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 el ejemplo de código anterior, some_table se declara automáticamente como dependencia de custom_assertion. Durante la ejecución, Dataform ejecuta some_table primero y, a continuación, ejecuta custom_assertion una vez que se ha creado some_table.

Declarar dependencias en el bloque config

Para declarar dependencias que no se referencian en la definición de la instrucción SQL de la dependencia, pero que deben ejecutarse antes de la tabla, la aserción o la operación SQL personalizada, sigue estos pasos:

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

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

    dependencies: [ "DEPENDENCY", ]

    Sustituye DEPENDENCY por la cadena de destino. Por ejemplo, el nombre de archivo de la acción que quieras añadir como dependencia. Puedes introducir varios objetivos separados por comas.

  4. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestran la tabla some_table y la aserción some_assertion añadidas como dependencias al bloque config de un archivo de definición de tabla:

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

Definir 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, el fallo 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 cumplen las aserciones de la acción A, debes definir las aserciones de la acción A como dependencias de la acción B.

Puedes definir aserciones como dependencias de una acción seleccionada de las siguientes formas:

Definir las aserciones seleccionadas como dependencias

Puedes definir manualmente las aserciones seleccionadas como dependencias añadiéndolas a la línea dependencies: [ "" ] del 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 seleccionadas de la acción A, puedes añadir esas aserciones seleccionadas al bloque config de la acción B.

Puedes definir manualmente las aserciones seleccionadas como dependencias de todos los tipos de acción, excepto las declaraciones de fuentes de datos.

Definir las aserciones de una acción de dependencia seleccionada como dependencias

Puedes definir el parámetro includeDependentAssertions para que se establezcan 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 añade 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 definir el parámetro includeDependentAssertions para que todas las aserciones de la acción A se definan automáticamente como dependencias de la acción C.

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

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

Puede definir el parámetro dependOnDependencyAssertions para que se definan 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 añade 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 definir el parámetro dependOnDependencyAssertions para que se definan automáticamente todas las aserciones de las acciones A y B como dependencias de la acción C.

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

  • table
  • view
  • operations

Si define el parámetro dependOnDependencyAssertions y los parámetros includeDependentAssertions en un mismo archivo, el parámetro includeDependentAssertions tiene prioridad. Por ejemplo, si asignas el valor true a dependOnDependencyAssertions, pero también asignas el valor false a includeDependentAssertions para una acción de dependencia seleccionada, Dataform no añadirá las aserciones de esa acción a las dependencias.

En el siguiente ejemplo de código se muestran los parámetros dependOnDependencyAssertions y includeDependentAssertions definidos 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 el ejemplo de código anterior, Dataform añade todas las aserciones directas de actionA y actionC a las dependencias de tableName durante la compilación.

Definir las aserciones seleccionadas como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se cumplan las aserciones seleccionadas, puedes añadir la aserción seleccionada a la línea dependencies: [ "" ] del bloque config de la acción editada.

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

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, despliega definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.
  3. En el bloque config del archivo de acciones, introduce dependencies: [ "" ].

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

    nonNull

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

    Haz los cambios siguientes:

    • ACTION_TYPE: el tipo de acción del flujo de trabajo: table, view o operations.
    • ACTION_DATASET_NAME: 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: 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"]
}

    Haz los cambios siguientes:

    • ACTION_TYPE: el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: 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: 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"]
}

    Haz los cambios siguientes:

    • ACTION_TYPE: el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: 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: el nombre de la tabla en la que se define la aserción.
    • INDEX: el índice del array de claves definido en la aserción uniqueKey que quieras añadir como dependencia (por ejemplo, 0 o 1). Si solo se define una matriz de claves en la aserción, el índice es 0.

    uniqueKeys

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

    Haz los cambios siguientes:

    • ACTION_TYPE: el tipo de acción del flujo de trabajo: table, view o operations.
    • DATASET_NAME: 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: el nombre de la tabla en la que se define la aserción.
    • INDEX: el índice del array de claves definido en la aserción uniqueKeys que quieras añadir como dependencia (por ejemplo, 0 o 1). Si solo se define una matriz de claves en la aserción, el índice es 0.

    aserción manual

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

    Haz los cambios siguientes:

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

  5. Para añadir otra aserción como dependencia a la tabla editada, repite el paso 4.

  6. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestran las aserciones añadidas 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 el siguiente ejemplo de código se muestran las aserciones de la tabla A añadidas como dependencias a la tabla B:

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

En el siguiente ejemplo de código se muestra una aserción manual definida en el archivo manualAssertion.sqlx y añadida como dependencia a una vista:

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

En el siguiente ejemplo de código se muestra el archivo manual_assertion y las aserciones de la tabla sometable añadidas 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 ...

Definir las aserciones de una acción seleccionada como dependencias

Para ejecutar una acción de flujo de trabajo solo cuando se cumplan todas las aserciones directas de una acción de dependencia seleccionada, asigna el valor true al parámetro includeDependentAssertions en la acción editada. Dataform añade 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 definir todas las aserciones de una acción de dependencia seleccionada como dependencias, sigue estos pasos:

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, despliega definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.

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

    En el bloque config

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

    Haz los cambios siguientes:

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

    En la instrucción SELECT

      config { type: "ACTION_TYPE" }

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

    Haz los cambios siguientes:

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

  4. Opcional: Haz clic en Formato.

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

Definir las aserciones de todas las acciones de dependencia como dependencias

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

Si define el parámetro dependOnDependencyAssertions y los parámetros includeDependentAssertions en un mismo archivo, el parámetro includeDependentAssertions tendrá prioridad en la acción de dependencia para la que se haya definido.

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

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, despliega definitions/.
  2. Selecciona un archivo SQLX de acción de flujo de trabajo.

  3. En el archivo, asigna el valor true al parámetro dependOnDependencyAssertions con el siguiente formato:

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

    Sustituye 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 el siguiente ejemplo de código se muestra sometableE, que depende de sometableA, sometabletableB, sometableC, 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 el ejemplo de código anterior, Dataform añade automáticamente todas las aserciones directas de sometableA, sometableB, sometableC y sometableD como dependencias de sometableE durante la compilación.

Hacer referencia a una tabla con un nombre de tabla sustituido

  • Para hacer referencia a una tabla con un nombre de tabla sustituido, en la función ref, introduce el nombre de tabla sustituido que se ha definido en name: "".

En el siguiente ejemplo de código se hace referencia a una tabla cuyo nombre se ha sustituido por overridden_name:

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

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

Siguientes pasos