Administra un repositorio

En este documento, se muestra cómo hacer lo siguiente en Dataform:

• Configura los parámetros del flujo de trabajo de Dataform.
• Administra el paquete principal de Dataform.
• Control de versiones de tu código.

Antes de comenzar

1. Selecciona o crea un repositorio.

   Nota: La lista de repositorios de Dataform solo incluye los repositorios creados para el desarrollo de flujos de trabajo de Dataform. Los repositorios de los recursos de BigQuery Studio, como los notebooks o las consultas guardadas, se administran por separado y no aparecen en esta lista.

2. Opcional: Conecta tu repositorio a un repositorio de Git de terceros.

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

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Configurar los parámetros de Dataform y administrar la ubicación del paquete principal de Dataform: Administrador de Dataform (roles/dataform.admin) en repositorios
• Actualiza el paquete principal de Dataform y usa el control de versión en Dataform: Editor de Dataform (roles/dataform.editor) en 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 a través de roles personalizados o cualquier otro rol predefinido.

Establece la configuración del flujo de trabajo de Dataform

En esta sección, se muestra cómo editar la configuración de procesamiento del flujo de trabajo 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

Para todos los repositorios, se requiere una cuenta de servicio personalizada para la ejecución del flujo de trabajo y se aplica el modo act-as estricto. No puedes usar el agente de servicio predeterminado de Dataform para ejecutar flujos de trabajo.

Cada repositorio de Dataform contiene un archivo de configuración de flujo de trabajo único. El archivo contiene el ID del proyecto Google Cloud y el esquema en el que Dataform publica recursos en BigQuery. Dataform usa la configuración predeterminada que puedes anular para que se adapte 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 las versiones anteriores de Dataform Core, la configuración del flujo de trabajo se almacena en el archivo dataform.json. Ambos archivos de configuración deben estar en el directorio raíz de tu repositorio. El archivo workflow_settings.yaml de Dataform Core 3.0 es retrocompatible con el archivo dataform.json. Puedes seguir usando el archivo 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 futura.

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 formato YAML.

En el siguiente muestra 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
  dataformCoreVersion: 3.0.62
  preserveGovernanceControls: true

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

• defaultProject: ID del proyecto de BigQuery Google Cloud
• defaultDataset: Es el conjunto de datos de BigQuery en el que Dataform crea recursos, llamado dataform de forma predeterminada.

• defaultLocation (opcional): Es la ubicación predeterminada de tu conjunto de datos de BigQuery. Dataform usa esta ubicación para procesar tu código y almacenar los resultados. Esta ubicación de procesamiento debe coincidir con la ubicación de tus conjuntos de datos de BigQuery. Sin embargo, no es necesario que coincida con la ubicación del repositorio de Dataform.

  Si no configuras el parámetro defaultLocation, Dataform determina la ubicación en función de los conjuntos de datos a los que hace referencia tu consulta en SQL. Esto funciona de la siguiente manera:

  • Si tu consulta hace referencia a conjuntos de datos de la misma ubicación, Dataform usa esa ubicación.
  • Si tu consulta hace referencia a conjuntos de datos de dos o más ubicaciones diferentes, se produce un error. Para obtener detalles sobre esta limitación, consulta Replicación de conjuntos de datos entre regiones.
  • Si tu consulta no hace referencia a ningún conjunto de datos, la ubicación predeterminada para Dataform es la multirregión US. Para elegir una ubicación diferente, establece la ubicación predeterminada. Como alternativa, usa la variable del sistema @@location en tu consulta. Para obtener más información, consulta Cómo especificar ubicaciones.

• defaultAssertionDataset: Es el conjunto de datos de BigQuery en el que Dataform crea vistas con resultados de aserción, llamado dataform_assertions de forma predeterminada.

• dataformCoreVersion: Es la versión del paquete principal de Dataform instalado en tu repositorio. Para obtener más información, consulta Administra el paquete principal de Dataform.

• preserveGovernanceControls (opcional): Es un valor booleano que especifica si Dataform conserva automáticamente las políticas de datos y las etiquetas de administración de datos de BigQuery existentes (versión preliminar) cuando se vuelven a crear tablas en las ejecuciones de flujos de trabajo. Para obtener más información, consulta Conserva los metadatos de los controles de acceso.

Para obtener más información sobre las propiedades de workflow_settings.yaml, consulta WorkflowSettings 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 las opciones de workflow_settings.yaml a las opciones de dataform.projectConfig accesibles por código:

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

En el siguiente muestra de código, se muestra el objeto dataform.projectConfig al que se hace referencia en una instrucción 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 muestra 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: un puntero a BigQuery, en el que Dataform crea recursos.
• defaultDatabase: ID del proyecto de BigQuery Google Cloud
• defaultSchema: el conjunto de datos de BigQuery en el que Dataform crea recursos.

• defaultLocation (opcional): Es la ubicación predeterminada de tu conjunto de datos de BigQuery. Dataform usa esta ubicación para procesar tu código y almacenar los resultados. Esta ubicación de procesamiento debe coincidir con la ubicación de tus conjuntos de datos de BigQuery. Sin embargo, no es necesario que coincida con la ubicación del repositorio de Dataform.

  Si no configuras el parámetro defaultLocation, Dataform determina la ubicación en función de los conjuntos de datos a los que hace referencia tu consulta en SQL. Esto funciona de la siguiente manera:

  • Si tu consulta hace referencia a conjuntos de datos de la misma ubicación, Dataform usa esa ubicación.
  • Si tu consulta hace referencia a conjuntos de datos de dos o más ubicaciones diferentes, se produce un error. Para obtener detalles sobre esta limitación, consulta Replicación de conjuntos de datos entre regiones.
  • Si tu consulta no hace referencia a ningún conjunto de datos, la ubicación predeterminada para Dataform es la multirregión US. Para elegir una ubicación diferente, establece la ubicación predeterminada. Como alternativa, usa la variable del sistema @@location en tu consulta. Para obtener más información, consulta Especifica ubicaciones.

• assertionSchema: Es el conjunto de datos de BigQuery en el que Dataform crea vistas con resultados de aserción, llamado dataform_assertions de forma predeterminada.

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

Configura nombres de esquemas

Para configurar los nombres de esquema, debes editar las propiedades defaultDataset y defaultAssertionSchema en el archivo workflow_settings.yaml, o bien 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 espacio de trabajo de desarrollo, en el panel Archivos, 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 observa un nombre de defaultDataset personalizado definido en el archivo workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

1. En el espacio de trabajo de desarrollo, en el panel Archivos, haz clic en el archivo dataform.json.

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

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

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

Cómo crear 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 versión 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 un parámetro de configuración de la versión 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 todo un repositorio, sigue estos pasos:

workflow_settings.yaml

1. Ve a tu espacio 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": {
     "VARIABLE":"VALUE"
   }
   

   Reemplaza lo siguiente:

   • VARIABLE: Un nombre para la variable
   • VALUE: Es 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 indica 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 espacio 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": {
     "VARIABLE":"VALUE"
   }
   

   Reemplaza lo siguiente:

   • VARIABLE: Un nombre para la variable
   • VALUE: Es el valor predeterminado de la variable de compilación.

En la siguiente muestra de código, se observa 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 indica 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"
}
}

Agrega una variable de compilación a una tabla

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

1. Ve a tu espacio de trabajo de desarrollo de Dataform.
2. En el panel Archivos, selecciona un archivo de definición de tabla SQLX.

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

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

   Reemplaza lo siguiente:

   • VARIABLE: el nombre de tu variable, por ejemplo, executionSetting
   • SET_VALUE: Un valor para la variable, por ejemplo, staging
   • CONDITION: Es una condición para la ejecución de la tabla.

En la siguiente muestra de código, se indica 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 el parámetro de configuración de ejecución de 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!"
  )}

Configura los valores predeterminados a nivel del flujo de trabajo para las tablas de Iceberg

Puedes proporcionar valores predeterminados a nivel del flujo de trabajo para las tablas administradas de Apache Iceberg en el archivo workflow_settings.yaml. Puedes establecer valores predeterminados para el nombre del bucket, la raíz de la carpeta de la tabla y la ruta de acceso secundaria de la carpeta de la tabla.

Dataform usa estos valores predeterminados para construir el URI de almacenamiento de una tabla administrada de Iceberg si no los estableces en el bloque config del archivo de definición de la tabla.

Para configurar los valores predeterminados a nivel de flujo de trabajo para las tablas, agrega el bloque defaultIcebergConfig con los siguientes campos a tu archivo workflow_settings.yaml:

• bucketName: Opcional Es el nombre predeterminado del bucket de Cloud Storage.
• tableFolderRoot: Opcional Es el nombre predeterminado de la carpeta de primer nivel dentro del bucket de Cloud Storage.
• tableFolderSubpath: Opcional Es el nombre predeterminado de una subcarpeta dentro de tableFolderRoot.

En la siguiente muestra de código, se observa un archivo workflow_settings.yaml con valores predeterminados a nivel de flujo de trabajo para las tablas administradas de Iceberg:

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

Puedes acceder a estos campos en tu código de Dataform como propiedades del objeto ProjectConfig:

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

Para obtener más información, consulta Crea tablas administradas de Apache Iceberg y las propiedades del bloque iceberg.

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

Para asegurarte de que el archivo de configuración del flujo de trabajo sea compatible con las versiones futuras del framework de Dataform Core, 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 Dataform Core es el único paquete de dependencia en tu repositorio, el archivo workflow_settings.yaml también reemplaza al archivo package.json. Para obtener más información sobre cómo reemplazar el archivo package.json por el archivo workflow_settings.yaml, consulta Administra el paquete principal de Dataform.

En la siguiente tabla, se muestra la asignación de las propiedades de configuración del flujo de trabajo del archivo dataform.json al archivo 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 predeterminado del proyecto de Google Cloud .
defaultLocation	defaultLocation	Es opcional. Es la ubicación predeterminada de BigQuery en la que Dataform crea tablas. Si no se configura, Dataform determina la ubicación en función de los conjuntos de datos a los que hace referencia tu consulta en SQL. Para obtener más información, consulta Especifica ubicaciones.
defaultSchema	defaultDataset	Obligatorio. Es el conjunto de datos predeterminado.
databaseSuffix	projectSuffix	Es opcional. Es el sufijo que se agregará a todas las referencias del proyecto de Google Cloud .
schemaSuffix	datasetSuffix	Es opcional. Es el sufijo que se agregará a todos los conjuntos de datos de acciones.
tablePrefix	namePrefix	Es opcional. Es el prefijo que se antepone a todos los nombres de las acciones.
vars	vars	Es 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 está 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.

   Ir a Dataform

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

3. En el panel Archivos, haz clic en addAgregar y, luego, en Crear archivo.

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, asignada 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 muestran los parámetros de configuración del flujo de trabajo definidos 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 observa el archivo dataform.json anterior convertido a workflow_settings.yaml:

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

Administra el paquete principal de Dataform

En esta sección, se muestra cómo administrar el paquete de dependencia del framework principal de Dataform y actualizarlo a la versión más reciente.

Dataform Core es el framework de código abierto de Dataform para desarrollar flujos de trabajo con SQL, SQLX y JavaScript. Como práctica recomendada, usa siempre la versión más reciente disponible del framework de Dataform Core. Para obtener información sobre las versiones del framework principal de Dataform, consulta Versiones de Dataform en GitHub.

Administra la ubicación del paquete de Dataform Core

Cuando inicializas el primer espacio de trabajo en un repositorio, Dataform establece automáticamente Dataform Core como un paquete de dependencias. A partir de Dataform Core 3.0.0, Dataform instala el paquete de Dataform Core en el archivo workflow_settings.yaml de forma predeterminada. En versiones anteriores de Dataform Core, Dataform Core se configuraba en el archivo package.json.

En Dataform Core 3.0.0 y versiones posteriores, si Dataform Core es el único paquete en tu repositorio, debes configurarlo en el archivo workflow_settings.yaml. En el caso de los repositorios creados con versiones anteriores de Dataform Core, mueve el paquete de Dataform Core a workflow_settings.yaml.

El archivo package.json es necesario para instalar paquetes adicionales en Dataform. Si tu repositorio usa paquetes adicionales, configura el paquete principal de Dataform en package.json para que todos los paquetes se configuren en un solo lugar. Si tu repositorio no tiene el archivo package.json, crea el archivo package.json y mueve el paquete principal de Dataform para instalar paquetes adicionales. El archivo package.json debe estar en el directorio raíz de tu repositorio.

Mover Dataform core a workflow_settings.yaml

En el caso de los repositorios creados con versiones de Dataform Core anteriores a 3.0.0, si no tienes paquetes de dependencias que no sean Dataform Core, debes mover el paquete de Dataform Core del archivo package.json al archivo workflow_settings.yaml y borrar el archivo package.json redundante.

Para migrar el paquete principal de Dataform del archivo package.json al archivo workflow_settings.yaml, haz lo siguiente:

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

   Ir a Dataform

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

3. En el panel Archivos, selecciona el archivo workflow_settings.yaml.

4. En el archivo workflow_settings.yaml, agrega el paquete principal de Dataform en el siguiente formato:

   dataformCoreVersion: "VERSION"
   
   

   Reemplaza VERSION por la versión más reciente de Dataform, por ejemplo, 3.0.0.

5. En el panel Archivos, haz clic en el menú Más junto al archivo package.json y, luego, en Borrar.

6. Para confirmar la eliminación del archivo dataform.json, haz clic en Borrar.

7. Haz clic en Instalar paquetes.

Mover Dataform core a package.json

El archivo package.json es necesario para instalar paquetes adicionales en un repositorio. Si tu repositorio usa paquetes adicionales, debes almacenar todos los paquetes, incluido el paquete principal de Dataform, en el archivo package.json.

Si tu repositorio no contiene el archivo package.json porque el paquete principal de Dataform está configurado en el archivo workflow_settings.yaml, debes crear el archivo package.json para instalar paquetes adicionales y, luego, mover el paquete principal de Dataform del archivo workflow_settings.yaml al archivo package.json recién creado.

Para crear el archivo package.json y mover el paquete principal de Dataform, sigue estos pasos:

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

   Ir a Dataform

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

3. En el panel Archivos, haz clic en addAgregar y, luego, en Crear archivo.

4. En el campo Agregar una ruta de acceso al archivo, ingresa package.json.

5. Haz clic en Crear archivo.

6. En el archivo package.json, agrega el paquete principal de Dataform con el siguiente formato:

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Reemplaza VERSION por la versión más reciente de Dataform, por ejemplo, 3.0.0.

7. Haz clic en Instalar paquetes.

8. En el panel Archivos, selecciona workflow_settings.yaml.

9. En el archivo workflow_settings.yaml, borra la propiedad dataformCoreVersion.

Actualiza Dataform Core

Siempre prueba las versiones nuevas de los paquetes en un entorno que no sea de producción antes de implementarlas en tu entorno de producción.

Para actualizar el paquete de dependencias de Dataform Core, sigue estos pasos:

1. Busca la versión más reciente de @dataform/core en la página de versiones de Dataform en GitHub.

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

   Ir a Dataform

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

4. En el panel Archivos, selecciona el archivo package.json o el archivo workflow_settings.yaml.

   La ubicación en la que se establece el paquete de dependencia principal de Dataform depende de tu versión de Dataform Core y de tu uso de paquetes. Para obtener más información, consulta Administra la ubicación del paquete principal de Dataform.

5. Actualiza el paquete de dependencias de Dataform Core con la versión más reciente:

   package.json

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Reemplaza VERSION por la versión más reciente de Dataform, por ejemplo, 3.0.0. Para evitar problemas con la instalación del paquete, especifica de forma explícita la versión del paquete principal de Dataform. No uses otras opciones de dependencies del archivo package.json, por ejemplo, >version.

   workflow_settings.yaml

   dataformCoreVersion: "VERSION"
   

   Reemplaza VERSION por la versión más reciente de Dataform, por ejemplo, 3.0.0.

6. Haz clic en Instalar paquetes.

7. Confirma los cambios.

8. Envía los cambios a tu repositorio.

En la siguiente muestra de código, se observa la dependencia de @dataform/core actualizada a la versión 3.0.0 en el archivo package.json:

{
    "dependencies": {
        "@dataform/core": "3.0.0"
    }
}

Aplica el control de versiones en tu código

En esta sección, se muestra cómo usar el control de versión en Dataform para realizar un seguimiento del desarrollo.

Dataform usa Git para realizar un seguimiento de cada cambio que se hace en los archivos de un repositorio.

En un repositorio de Dataform, interactúas directamente con el repositorio de Git.

En un repositorio conectado, interactúas con la rama de seguimiento del repositorio remoto que configuraste mientras conectabas el repositorio.

Dataform muestra opciones de control de versión según el estado de los cambios en tu espacio de trabajo de desarrollo. Por ejemplo, Dataform muestra la opción de confirmación solo cuando hay cambios locales sin confirmar en tu espacio de trabajo. Cuando los archivos de tu espacio de trabajo son una copia exacta de tu rama predeterminada o de seguimiento, Dataform muestra el estado El espacio de trabajo está actualizado.

Dataform muestra las siguientes opciones de control de versión:

Confirma los cambios de X

Confirma la cantidad X de cambios locales en tu espacio de trabajo o los archivos modificados seleccionados. Dataform muestra los cambios sin confirmar.

Enviar a la rama predeterminada

Envía los cambios confirmados a la rama predeterminada. Esta opción está disponible en un repositorio de Dataform si no tienes cambios sin confirmar en tu espacio de trabajo.

Enviar a your-branch-name

Envía los cambios confirmados a your-branch-name. Esta opción está disponible en un repositorio conectado a un repositorio de Git de terceros si no tienes cambios sin confirmar en tu espacio de trabajo.

Extraer de la rama predeterminada

Actualiza tus espacios de trabajo con los cambios recientes de tu rama predeterminada. Esta opción está disponible en un repositorio de Dataform si no tienes cambios confirmados sin confirmar o sin enviar en tu espacio de trabajo.

Extraer de your-branch-name

Actualiza tu espacio de trabajo con los cambios recientes de your-branch-name. Esta opción está disponible en un repositorio conectado a un repositorio de Git de terceros si no tienes cambios confirmados o cambios confirmados sin enviar en tu espacio de trabajo.

Volver a la última confirmación

Restablece los archivos de tu espacio de trabajo al estado de tu última confirmación.

Extraer cambios

Si tu espacio de trabajo de desarrollo no está sincronizado con tu repositorio, Dataform mostrará la opción Pull. Para extraer los cambios de tu repositorio a tu espacio de trabajo de desarrollo, sigue estos pasos:

1. En la página Dataform, selecciona un repositorio.
2. En la pestaña Lugares de trabajo de desarrollo, selecciona un lugar de trabajo de desarrollo.
3. En la página del espacio de trabajo de desarrollo, haz lo siguiente:
   1. Si estás en un repositorio de Dataform, haz clic en Extraer de la rama predeterminada.
   2. Si estás en un repositorio conectado a un repositorio de Git de terceros, haz clic en Extraer de your-branch-name.

Confirmar cambios

Después de realizar un cambio en un espacio de trabajo de desarrollo, Dataform muestra la opción Confirmar. Puedes confirmar todos los cambios locales o los archivos seleccionados.

Nota: De forma predeterminada, Dataform usa la dirección de correo electrónico del usuario autenticadoGoogle Cloud para el autor de la confirmación, pero la API de Dataform permite establecer una dirección de correo electrónico personalizada para el autor de la confirmación. Este comportamiento es similar al del comando git commit --author y solo afecta al historial de confirmaciones de Git. La identidad del autor de la confirmación no se verifica de forma criptográfica.

En el diálogo New commit, Dataform muestra los cambios no confirmados.

Para confirmar los cambios de tu espacio de trabajo de desarrollo en tu repositorio, sigue estos pasos:

1. En la página Dataform, selecciona un repositorio.
2. En la página del repositorio, selecciona un espacio de trabajo de desarrollo.
3. En la página del espacio de trabajo de desarrollo, haz clic en Confirmar.

4. En el panel Nueva confirmación, haz lo siguiente:

   1. En el campo Agrega un mensaje de confirmación, ingresa una descripción para tu confirmación.

   2. Selecciona los archivos modificados que deseas confirmar.

      Si no seleccionas ningún archivo, Dataform confirmará todos los cambios locales. Puedes filtrar los archivos modificados por estado, nombre y ruta de acceso.

   3. Haz clic en Confirmar todos los cambios o en Confirmar X cambios.

      El nombre del botón depende de los archivos que selecciones para confirmar.

Enviar cambios

Dataform muestra la opción Enviar después de confirmar los cambios. Para enviar los cambios de tu espacio de trabajo de desarrollo a tu repositorio, sigue estos pasos:

1. En la página Dataform, selecciona un repositorio.
2. En la página del repositorio, selecciona un espacio de trabajo de desarrollo.
3. Confirma los cambios.
4. En la página del lugar de trabajo de desarrollo, haz lo siguiente:
   1. Si estás en un repositorio de Dataform, haz clic en Enviar a la rama predeterminada.
   2. Si estás en un repositorio conectado a un repositorio de Git de terceros, haz clic en Enviar a your-branch-name.

Revertir los cambios no confirmados

Para revertir los cambios no confirmados, sigue estos pasos:

1. En la página Dataform, selecciona un repositorio.
2. En la página del repositorio, selecciona un espacio de trabajo de desarrollo.
3. Sobre el panel Archivos, haz clic en el menú Más y, luego, selecciona Revert to last commit.

Cómo resolver conflictos de fusión

Un conflicto de combinación puede ocurrir cuando un cambio local en tu espacio de trabajo de desarrollo es incompatible con un cambio que se realizó en la rama de seguimiento predeterminada de tu repositorio. Por lo general, los conflictos de combinación se producen cuando varios usuarios editan el mismo archivo de forma simultánea.

Por lo general, se produce un conflicto de combinación cuando extraes datos de una rama después de que otro usuario envió un cambio conflictivo a la misma rama. Debes resolver un conflicto de combinación de forma manual editando el archivo afectado.

En la siguiente muestra de código, se muestra un conflicto de combinación en un archivo SQLX:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

Para resolver un conflicto de combinación, sigue estos pasos:

1. En tu espacio de trabajo de desarrollo, en el panel Archivos, selecciona un archivo afectado.
2. Edita el archivo con los cambios que elijas.
3. Confirma los cambios.
4. Opcional: Envía los cambios.

Identifica repositorios para los recursos de BigQuery

Los repositorios de Dataform que se crean y administran de forma automática con otra función de BigQuery, como los notebooks o las consultas guardadas, se ocultan en Dataform en la consola de Google Cloud para reducir el desorden y evitar la modificación accidental de la lógica específica de la función. Es posible que estos repositorios aparezcan en las búsquedas de Cloud Asset Inventory o en las auditorías de permisos de IAM, pero no aparecen en Dataform en la consola de Google Cloud .

Puedes identificar el origen de un repositorio de Dataform inspeccionando sus etiquetas de recursos. En la siguiente tabla, se describen las etiquetas que usan varias funciones de BigQuery:

Función	Clave de etiqueta	Valor de etiqueta
Repositorios de BigQuery	origin	bigquery-studio
Repositorios de Git de BigQuery Studio	origin	bigquery-studio-git-folder
Lienzos de datos	single-file-asset-type	data_canvas
Preparaciones de datos	single-file-asset-type	data_preparation o data_preparation_sqlx
Notebooks	single-file-asset-type	notebook
Canalizaciones	bigquery-workflow	(Cualquier valor)
Consultas guardadas	single-file-asset-type	sql

Para recuperar las etiquetas de un repositorio que no aparece en Dataform, selecciona una de las siguientes opciones:

Console

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

   Ir a Asset Inventory

2. Haz clic en la pestaña Recurso.

3. En el panel Filtrar resultados, junto a Tipo de recurso, haz clic en Ver más y, luego, ingresa dataform.googleapis.com/Repository.

4. Selecciona dataform.Repository y, luego, haz clic en Aplicar.

5. En la tabla de resultados, busca tu repositorio y revisa la columna Etiquetas. Compara las etiquetas encontradas con la tabla que describe las etiquetas que usan varias funciones de BigQuery para identificar la función fuente.

API

Para recuperar etiquetas, usa el método projects.locations.repositories.get. Ejecuta la solicitud a la API con la siguiente información:

• Extremo: GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID

Como alternativa, en la terminal, ejecuta el siguiente comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID"

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la región en la que se encuentran los recursos de Dataform.
• REPOSITORY_ID: Es el identificador único del repositorio de Dataform que consultas.

El recurso projects.locations.repositories que se muestra en la respuesta contiene un mapa de etiquetas con los metadatos que se usan para identificar el atributo de origen.

gcloud

Ejecuta el siguiente comando en Google Cloud CLI para recuperar las etiquetas de un repositorio específico:

gcloud asset search-all-resources \
    --asset-types=dataform.googleapis.com/Repository \
    --query="name:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID" \
    --format="yaml(labels)"

Reemplaza lo siguiente:

• PROJECT_ID: Es el identificador único de tu proyecto de Google Cloud .
• LOCATION: Es la región de Google Cloud en la que se encuentra tu repositorio.
• REPOSITORY_ID: Es el identificador único de tu repositorio de Dataform nuevo.

Para ubicar el recurso correspondiente a la etiqueta de salida, navega a la página de atributos coincidente en la consola de Google Cloud , por ejemplo, las carpetas Notebooks o Lienzos de datos en la pestaña Explorador del panel izquierdo en BigQuery Studio.

¿Qué sigue?

• Para obtener más información sobre la configuración del proyecto de Dataform, consulta la referencia de IProjectConfig.
• Para obtener información sobre cómo instalar paquetes adicionales, consulta Instala un paquete en Dataform.
• Para aprender a crear una tabla, consulta Crea una tabla.