Configura la configuración del flujo de trabajo de Dataform

En esta página, se muestra cómo editar la configuración de procesamiento del flujo de trabajo de SQL de Dataform para un repositorio específico.

Te recomendamos que edites el archivo de configuración para cambiar el nombre de los esquemas o agregar variables de compilación personalizadas a tu repositorio.

Acerca de la configuración del repositorio

Cada repositorio de Dataform contiene un archivo de configuración de flujo de trabajo único. El archivo contiene el ID del proyecto de Google Cloud y el esquema en el que Dataform publica recursos en BigQuery. Dataform usa la configuración predeterminada que puedes anular para adaptarla mejor a tus necesidades editando el archivo de configuración.

A partir de Dataform core 3.0.0, la configuración del flujo de trabajo se almacena en el archivo workflow_settings.yaml de forma predeterminada. En versiones anteriores del núcleo de Dataform, la configuración del flujo de trabajo se almacena en el archivo dataform.json. El archivo workflow_settings.yaml de Dataform core 3.0 es retrocompatible con dataform.json. Puedes seguir usando dataform.json para almacenar la configuración del flujo de trabajo. Como práctica recomendada, debes migrar la configuración del flujo de trabajo de tu repositorio al formato workflow_settings.yaml para garantizar la compatibilidad en el futuro.

Acerca de workflow_settings.yaml

El archivo workflow_settings.yaml, que se introdujo en Dataform core 3.0, almacena la configuración del flujo de trabajo de Dataform en el formato YAML.

En el siguiente ejemplo de código, se muestra un archivo workflow_settings.yaml de muestra:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

En la muestra de código anterior, los pares clave-valor se describen de la siguiente manera:

  • defaultProject: Es el ID de tu proyecto de BigQuery de Google Cloud.
  • defaultDataset: Es el conjunto de datos de BigQuery en el que Dataform crea recursos, llamado dataform de forma predeterminada.
  • defaultLocation: Es la región predeterminada de tu conjunto de datos de BigQuery. Para obtener más información sobre las ubicaciones de los conjuntos de datos de BigQuery, consulta Ubicaciones de conjuntos de datos. En esta ubicación, Dataform procesa tu código y almacena los datos ejecutados. Esta región de procesamiento debe coincidir con la ubicación de tus conjuntos de datos de BigQuery, pero no es necesario que coincida con la región del repositorio de Dataform.
  • defaultAssertionDataset: Es el conjunto de datos de BigQuery en el que Dataform crea vistas con resultados de aserción, que se denominan dataform_assertions de forma predeterminada.

Para obtener más información sobre las propiedades workflow_settings.yaml, consulta la referencia de configuraciones para la configuración de flujos de trabajo en GitHub.

Puedes acceder a las propiedades definidas en workflow_settings.yaml en tu código de Dataform como propiedades del objeto dataform.projectConfig.

Se aplican las siguientes asignaciones de opciones de workflow_settings.yaml a las opciones de dataform.projectConfig accesibles para el código:

  • defaultProject => defaultDatabase.
  • defaultDataset => defaultSchema.
  • defaultAssertionDataset => assertionSchema.
  • projectSuffix => databaseSuffix.
  • datasetSuffix => schemaSuffix.
  • namePrefix => tablePrefix.

En la siguiente muestra de código, se muestra el objeto dataform.projectConfig al que se hace referencia en una sentencia SELECT en una vista:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

Acerca de dataform.json

El archivo dataform.json almacena la configuración del flujo de trabajo de Dataform en el formato JSON.

En el siguiente ejemplo de código, se muestra un archivo dataform.json de muestra:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

En la muestra de código anterior, los pares clave-valor se describen de la siguiente manera:

  • warehouse: Es un puntero a BigQuery, donde Dataform crea recursos.
  • defaultDatabase: Es el ID de tu proyecto de BigQuery de Google Cloud.
  • defaultSchema: Es el conjunto de datos de BigQuery en el que Dataform crea recursos.
  • defaultLocation: Es la región predeterminada de tu conjunto de datos de BigQuery. Para obtener más información sobre las ubicaciones de los conjuntos de datos de BigQuery, consulta Ubicaciones de conjuntos de datos. En esta ubicación, Dataform procesa tu código y almacena los datos ejecutados. Esta región de procesamiento debe coincidir con la ubicación de tus conjuntos de datos de BigQuery, pero no es necesario que coincida con la región del repositorio de Dataform.
  • assertionSchema: Es el conjunto de datos de BigQuery en el que Dataform crea vistas con resultados de aserción, que se denominan dataform_assertions de forma predeterminada.

Puedes acceder a las propiedades definidas en dataform.json en el código de tu proyecto como propiedades del objeto dataform.projectConfig.

Antes de comenzar

  1. Crea un repositorio.

  2. Crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.

Roles obligatorios

Para obtener los permisos que necesitas para configurar la configuración de Dataform, pídele a tu administrador que te otorgue el rol de IAM Administrador de Dataform (roles/dataform.admin) en los repositorios. 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.

Configura los nombres de los esquemas

Para configurar los nombres de los esquemas, debes editar las propiedades defaultDataset y defaultAssertionSchema en el archivo workflow_settings.yaml, o las propiedades defaultSchema y assertionSchema en el archivo dataform.json.

Para configurar el nombre de un esquema, sigue estos pasos:

workflow_settings.yaml

  1. En el panel Files de tu lugar de trabajo de desarrollo, haz clic en el archivo workflow_settings.yaml.

  2. Edita el valor de defaultDataset, defaultAssertionSchema o ambos.

En la siguiente muestra de código, se muestra un nombre defaultDataset personalizado definido en el archivo workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. En el panel Files de tu lugar de trabajo de desarrollo, haz clic en el archivo dataform.json.

  2. Edita el valor de defaultSchema, assertionSchema o ambos.

En la siguiente muestra de código, se muestra un nombre defaultSchema personalizado definido en el archivo dataform.json:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Crea variables de compilación personalizadas

Las variables de compilación contienen valores que puedes modificar con anulaciones de compilación en una configuración de lanzamiento o en una solicitud a la API de Dataform.

Después de definir una variable de compilación en workflow_settings.yaml y agregarla a las tablas seleccionadas, puedes modificar su valor en una configuración de lanzamiento o en las anulaciones de compilación de la API de Dataform para ejecutar tablas de forma condicional.

Para obtener más información sobre cómo ejecutar tablas de forma condicional con variables de compilación, consulta Introducción al ciclo de vida del código en Dataform.

Para crear una variable de compilación que puedas usar en un repositorio, sigue estos pasos:

workflow_settings.yaml

  1. Ve a tu lugar de trabajo de desarrollo de Dataform.
  2. En el panel Files, selecciona el archivo workflow_settings.yaml.

  3. Ingresa el siguiente fragmento de código:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Reemplaza lo siguiente:

    • YOUR_VARIABLE por un nombre para la variable.
    • VALUE con el valor predeterminado de la variable de compilación.

En la siguiente muestra de código, se muestra la variable de compilación myVariableName establecida en myVariableValue en el archivo workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

En la siguiente muestra de código, se muestra el archivo workflow_settings.yaml con la variable de compilación executionSetting establecida en dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Ve a tu lugar de trabajo de desarrollo de Dataform.
  2. En el panel Files, selecciona el archivo dataform.json.

  3. Ingresa el siguiente fragmento de código:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Reemplaza lo siguiente:

    • YOUR_VARIABLE por un nombre para la variable.
    • VALUE con el valor predeterminado de la variable de compilación.

En la siguiente muestra de código, se muestra la variable de compilación myVariableName establecida en myVariableValue en el archivo dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

En la siguiente muestra de código, se muestra el archivo dataform.json con la variable de compilación executionSetting establecida en dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Cómo agregar una variable de compilación a una tabla

Para agregar una variable de compilación a un archivo de definición de tablas SQLX, sigue estos pasos:

  1. Ve a tu lugar de trabajo de desarrollo de Dataform.
  2. En el panel Files, selecciona un archivo de definición de tablas SQLX.

  3. En el archivo, ingresa una cláusula when con el siguiente formato:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Reemplaza lo siguiente:

    • YOUR_VARIABLE por el nombre de tu variable, por ejemplo, executionSetting.
    • SET_VALUE con un valor para la variable, por ejemplo, staging.
    • CONDITION con una condición para la ejecución de la tabla

En la siguiente muestra de código, se muestra un archivo SQLX de definición de tabla con una cláusula when y la variable executionSetting que ejecuta el 10% de los datos en la configuración de ejecución de la etapa de pruebas:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

En la siguiente muestra de código, se muestra un archivo SQLX de definición de vista con una cláusula when y la variable myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Migra la configuración del flujo de trabajo a workflow_settings.yaml

Para asegurarte de que tu archivo de configuración de flujo de trabajo sea compatible con las versiones futuras del framework principal de Dataform, debes migrar la configuración del flujo de trabajo del archivo dataform.json al archivo workflow_settings.yaml.

El archivo workflow_settings.yaml reemplaza al archivo dataform.json.

Si el núcleo de Dataform es el único paquete de dependencia en tu repositorio, el archivo workflow_settings.yaml también reemplazará el archivo package.json. Para obtener más información sobre cómo reemplazar package.json por workflow_settings.yaml, consulta Administra el paquete principal de Dataform.

En la siguiente tabla, se muestra la asignación de propiedades de configuración de flujo de trabajo de dataform.json a workflow_settings.yaml:

Propiedad en dataform.json Propiedad en workflow_settings.yaml Descripción
assertionSchema defaultAssertionDataset Obligatorio. Es el conjunto de datos predeterminado para las aserciones.
defaultDatabase defaultProject Obligatorio. Es el nombre del proyecto Google Cloud predeterminado.
defaultLocation defaultLocation Obligatorio. La ubicación predeterminada de BigQuery en la que Dataform creará tablas. Para obtener más información sobre las ubicaciones de BigQuery, consulta Ubicaciones de conjuntos de datos.
defaultSchema defaultDataset Obligatorio. Es el conjunto de datos predeterminado.
databaseSuffix projectSuffix Opcional. Es el sufijo que se agregará a todas las referencias del proyecto Google Cloud .
schemaSuffix datasetSuffix Opcional. Es el sufijo que se agregará a todos los conjuntos de datos de acciones.
tablePrefix namePrefix Opcional. Es el prefijo que se antepone a todos los nombres de acciones.
vars vars Opcional. Son variables definidas por el usuario que se ponen a disposición del código del proyecto durante la compilación. Un objeto que contiene una lista de pares key: value.
warehouse - Obligatorio en dataform.json. Debe establecerse en bigquery. No disponible en workflow_settings.yaml.
- dataformCoreVersion No disponible en dataform.json. Se instala en workflow_settings.yaml de forma predeterminada para los repositorios nuevos. Para obtener más información, consulta Administra el paquete principal de Dataform.

Para migrar la configuración del flujo de trabajo a workflow_settings.yaml, sigue estos pasos:

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

    Ve a la página Dataform

  2. Selecciona un repositorio y, luego, un espacio de trabajo.

  3. En el panel Files, haz clic en addAdd y, luego, en Create file.

  4. En el campo Agregar una ruta de acceso al archivo, ingresa workflow_settings.yaml.

  5. Haz clic en Crear archivo.

  6. En el archivo workflow_settings.yaml, agrega la configuración de tu archivo dataform.json, asignado al formato YAML.

  7. En el panel Archivos, haz clic en el menú Más junto a dataform.json y, luego, en Borrar.

  8. Para confirmar la eliminación de dataform.json, haz clic en Borrar.

En la siguiente muestra de código, se muestra la configuración del flujo de trabajo definida en un archivo dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

En la siguiente muestra de código, se muestra el archivo dataform.json anterior convertido a workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

¿Qué sigue?