Configura anulaciones de compilación con la API de Dataform

En este documento, se muestra cómo crear y ejecutar un resultado de compilación con anulaciones de compilación mediante la API de Dataform.

Acerca de las anulaciones de compilación de la API de Dataform

Para ejecutar tu flujo de trabajo de SQL, Dataform compila tu código en SQL para crear un resultado de compilación. Luego, durante una invocación de flujo de trabajo, Dataform ejecuta el resultado de la compilación en BigQuery.

De forma predeterminada, Dataform usa la configuración del archivo de configuración del flujo de trabajo para crear el resultado de la compilación. Para aislar los datos ejecutados en diferentes etapas del ciclo de vida de desarrollo, puedes anular la configuración predeterminada con anulaciones de compilación.

Si pasas solicitudes a la API de Dataform en la terminal, puedes crear y ejecutar un resultado de compilación único con anulaciones de compilación. Puedes crear un resultado de compilación de un lugar de trabajo o de un commit de Git seleccionado.

Para crear un resultado de compilación con anulaciones de compilación, debes enviar la solicitud compilationResults.create de la API de Dataform. En la solicitud, debes especificar una fuente, un espacio de trabajo o un objeto commitish de Git para que Dataform compile en el resultado de la compilación. En el objeto CodeCompilationConfig de la solicitud compilationResults.create, puedes configurar las anulaciones de compilación.

Luego, puedes ejecutar el resultado de la compilación creada en una solicitud workflowInvocations.create a la API de Dataform.

Puedes configurar las siguientes anulaciones de compilación con la API de Dataform:

ProyectoGoogle Cloud: Proyecto Google Cloud en el que Dataform ejecuta el resultado de la compilación, establecido en workflow_settings.yaml como defaultProject o en dataform.json como defaultDatabase.

Prefijo de la tabla
Se agregó un prefijo personalizado a todos los nombres de las tablas en el resultado de la compilación.
Sufijo de esquema
Sufijo personalizado que se agrega al esquema de tablas definido en defaultDataset en workflow_settings.yaml, defaultSchema en dataform.json o en el parámetro schema en el bloque config de una tabla.

Valor de una variable de compilación: Es el valor de una variable de compilación que se usará en el resultado de la compilación. Puedes usar variables de compilación para ejecutar tablas de forma condicional.

Como alternativa a las anulaciones de compilación de la API de Dataform que solo puedes usar para un resultado de compilación, puedes configurar anulaciones de compilación del espacio de trabajo en la consola de Google Cloud.

Para obtener información sobre formas alternativas de configurar anulaciones de compilación en Dataform, consulta Introducción al ciclo de vida del código.

Antes de comenzar

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

    Ir a Dataform

  2. Selecciona o crea un repositorio.

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

Cómo establecer una fuente de resultados de compilación

Para enviar la solicitud compilationResults.create de la API de Dataform, debes especificar una fuente para el resultado de la compilación.

Puedes configurar un lugar de trabajo de Dataform o una rama, una etiqueta o un SHA de confirmación de Git como la fuente en la solicitud de compilationResults.create.

Cómo configurar un espacio de trabajo como fuente de resultados de compilación

  • En la solicitud compilationResults.create, propaga la propiedad workspace con la ruta de acceso de un espacio de trabajo de Dataform seleccionado en el siguiente formato:
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

Reemplaza lo siguiente:

  • PROJECT_NAME por el nombre de tu Google Cloud proyecto.
  • LOCATION con la ubicación de tu repositorio de Dataform, que se establece en la configuración del flujo de trabajo.
  • Reemplaza REPOSITORY_NAME por el nombre de tu repositorio de Dataform.
  • WORKSPACE_NAME por el nombre de tu lugar de trabajo de Dataform.

En la siguiente muestra de código, se muestra la propiedad workspace en la solicitud compilationResults.create establecida en un espacio de trabajo llamado "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Cómo configurar un commit de Git como fuente de resultados de compilación

  • En la solicitud compilationResults.create, propaga la propiedad gitCommitish con la rama, la etiqueta o el SHA de confirmación de Git seleccionados en el siguiente formato:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Reemplaza GIT_COMMITISH por la rama, la etiqueta o el SHA de confirmación de Git seleccionados para el resultado de la compilación.

En la siguiente muestra de código, se muestra la propiedad gitCommitish en la solicitud compilationResults.create establecida en "staging":

{
  "gitCommitish": "staging"
}

Anula el proyecto Google Cloud predeterminado

Para crear tablas de etapa de pruebas o de producción en un Google Cloud proyecto independiente del proyecto que se usa para el desarrollo, puedes pasar un ID de proyecto Google Cloud diferente en el objeto CodeCompilationConfig de la solicitud compilationResults.create de la API de Dataform.

Pasar un ID de proyecto predeterminado independiente en la solicitud compilationResults.create anula el ID de proyectoGoogle Cloud predeterminado configurado en el archivo de configuración del flujo de trabajo, pero no anula los IDs de proyecto Google Cloud configurados en tablas individuales.

  • Para anular el ID de proyecto Google Cloud predeterminado, establece la propiedad defaultDatabase en el Google Cloud ID de proyecto seleccionado en el objeto CodeCompilationConfig con el siguiente formato:

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

Reemplaza PROJECT_NAME por el Google Cloud ID del proyecto que deseas configurar para el resultado de la compilación.

Agrega un prefijo de tabla

Para identificar rápidamente las tablas del resultado de la compilación, puedes agregar un prefijo a todos los nombres de las tablas en el resultado de la compilación pasando el prefijo de la tabla en el objeto CodeCompilationConfig en la solicitud compilationResults.create de la API de Dataform.

  • Para agregar un prefijo de tabla, establece la propiedad tablePrefix en el objeto CodeCompilationConfig con el siguiente formato:
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Reemplaza PREFIX por el sufijo que deseas agregar, por ejemplo, _staging. Por ejemplo, si tu defaultDataset en workflow_settings.yaml está configurado como dataform, Dataform creará tablas en el esquema dataform_staging.

Agrega un sufijo de esquema

Para separar los datos de desarrollo, etapa y producción, puedes agregar un sufijo a los esquemas en un resultado de compilación. Para ello, pasa el sufijo del esquema en el objeto CodeCompilationConfig en la solicitud compilationResults.create de la API de Dataform.

  • Para agregar un sufijo de esquema, establece la propiedad schemaSuffix en el objeto CodeCompilationConfig en el siguiente formato:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Reemplaza SUFFIX por el sufijo que deseas agregar, por ejemplo, _staging. Por ejemplo, si tu defaultDataset en workflow_settings.yaml está configurado como dataform, Dataform creará tablas en el esquema dataform_staging.

Nota: El parámetro schemaSuffix CodeCompilationConfig anula los esquemas configurados en el bloque config de archivos individuales.

Ejecuta archivos seleccionados de forma condicional con variables de compilación

Para ejecutar una tabla seleccionada solo en una configuración de ejecución específica, puedes crear una variable de compilación para la configuración de ejecución y, luego, pasar su valor en el objeto CodeCompilationConfig en la solicitud compilationResults.create de la API de Dataform.

Para ejecutar una tabla de forma condicional en una configuración de ejecución específica con la API de Dataform, sigue estos pasos:

  1. Crea una variable de compilación y agrégala a las tablas seleccionadas.

  2. Establece el par clave-valor YOUR_VARIABLE y VALUE en el bloque codeCompilationConfig de una solicitud de compilación de la API de Dataform en el siguiente formato:

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

  3. Reemplaza YOUR_VARIABLE por el nombre de tu variable, por ejemplo, executionSetting.

  4. Reemplaza VALUE por el valor de la variable para este resultado de compilación que cumpla con la condición when establecida en las tablas seleccionadas.

En la siguiente muestra de código, se muestra la variable executionSetting que se pasa a una solicitud de compilación de la API de Dataform:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Ejecuta un resultado de compilación con anulaciones de compilación

En la siguiente muestra de código, se muestra un ID de resultado de compilación que se pasa en una solicitud workflowInvocations.create:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

¿Qué sigue?