Usar la CLI de Dataform de código abierto

En este documento se explica cómo usar la interfaz de línea de comandos (CLI) de código abierto de Dataform para desarrollar flujos de trabajo de forma local mediante la terminal.

Con la CLI de código abierto de Dataform, puedes inicializar, compilar, probar y ejecutar Dataform Core de forma local, fuera de Google Cloud.

La CLI de Dataform admite las credenciales predeterminadas de la aplicación (ADC). Con ADC, puedes poner las credenciales a disposición de tu aplicación en varios entornos, como el de desarrollo local o el de producción, sin necesidad de modificar el código de la aplicación. Para usar ADC, primero debes proporcionar tus credenciales a ADC.

Nota: Desde Dataform core 3.0.0., Dataform no distribuye una imagen de Docker. Puedes crear tu propia imagen de Docker de Dataform, que puedes usar para ejecutar el equivalente de los comandos de la CLI de Dataform. Para crear tu propia imagen de Docker, consulta el artículo Contenerizar una aplicación de la documentación de Docker.

Antes de empezar

Antes de instalar la CLI de Dataform, instala NPM.

Instalar la CLI de Dataform

• Para instalar la CLI de Dataform, ejecuta el siguiente comando:

  npm i -g @dataform/cli@^3.0.0-beta
  

Inicializar un proyecto de Dataform

• Para inicializar un proyecto de Dataform, ejecuta el siguiente comando en el directorio del proyecto:

  dataform init . PROJECT_NAME DEFAULT_LOCATION
  

  Haz los cambios siguientes:

  • PROJECT_NAME: el nombre de tu proyecto.

  • DEFAULT_LOCATION (opcional): la ubicación en la que quieres que Dataform escriba los datos de BigQuery. Si no se define, Dataform determina la ubicación en función de los conjuntos de datos a los que hace referencia la consulta SQL. Funciona de la siguiente manera:

    • Si tu consulta hace referencia a conjuntos de datos de la misma ubicación, Dataform usará esa ubicación.
    • Si tu consulta hace referencia a conjuntos de datos de dos o más ubicaciones diferentes, se producirá un error. Para obtener más información sobre esta limitación, consulta el artículo Réplica de conjuntos de datos entre regiones.
    • Si tu consulta no hace referencia a ningún conjunto de datos, la ubicación predeterminada de Dataform es la US multirregión. Para elegir otra ubicación, define la ubicación predeterminada. También puedes usar la variable de sistema @@location en tu consulta. Para obtener más información, consulta Especificar ubicaciones.

Actualizar el núcleo de Dataform

• Para actualizar el framework principal de Dataform, actualiza el archivo dataformCoreVersion en workflow_settings.yaml y vuelve a ejecutar la instalación de NPM:

  npm i
  

Actualizar la CLI de Dataform

• Para actualizar la herramienta de línea de comandos de Dataform, ejecuta el siguiente comando:

  npm i -g @dataform/cli@^3.0.0-beta.2
  

Crear un archivo de credenciales

Dataform requiere un archivo de credenciales para conectarse a servicios remotos y crear el archivo .df-credentials.json en tu disco.

Advertencia: Si usas un sistema de control de versiones, no confirmes el archivo df-credentials.json. en tu repositorio para proteger estas credenciales de acceso. Te recomendamos que añadas el archivo .df-credentials.json a .gitignore.

Para crear el archivo de credenciales, sigue estos pasos:

1. Ejecuta el siguiente comando:

   dataform init-creds
   

2. Sigue el asistente init-creds, que te guiará por el proceso de creación del archivo de credenciales.

Crear un proyecto

Un proyecto de Dataform vacío en Dataform core 3.0.0-beta.0 o versiones posteriores tiene la siguiente estructura:

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

• Para crear un proyecto de Dataform en el que desplegar recursos en BigQuery, ejecuta el siguiente comando:

  dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
  

  Haz los cambios siguientes:

  • PROJECT_NAME: el nombre de tu proyecto.
  • YOUR_GOOGLE_CLOUD_PROJECT_ID: tu ID de proyecto Google Cloud .

  • DEFAULT_LOCATION (opcional): la ubicación en la que quieres que Dataform escriba los datos de BigQuery. Si no se define, Dataform determina la ubicación en función de los conjuntos de datos a los que hace referencia la consulta SQL. Funciona de la siguiente manera:

    • Si tu consulta hace referencia a conjuntos de datos de la misma ubicación, Dataform usará esa ubicación.
    • Si tu consulta hace referencia a conjuntos de datos de dos o más ubicaciones diferentes, se producirá un error. Para obtener más información sobre esta limitación, consulta el artículo Réplica de conjuntos de datos entre regiones.
    • Si tu consulta no hace referencia a ningún conjunto de datos, la ubicación predeterminada de Dataform es la US multirregión. Para elegir otra ubicación, define la ubicación predeterminada. También puedes usar la variable de sistema @@location en tu consulta. Para obtener más información, consulta Especificar ubicaciones.

Clonar un proyecto

Para clonar un proyecto de Dataform desde un repositorio de Git de terceros, sigue las instrucciones de tu proveedor de Git.

• Una vez que se haya clonado el repositorio, ejecuta el siguiente comando en el directorio del repositorio clonado:

  dataform install
  

Definir una tabla

Almacena las definiciones en la carpeta definitions/.

• Para definir una tabla, ejecuta el siguiente comando:

  echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx
  

  Haz los cambios siguientes:

  • TABLE_TYPE: el tipo de tabla: table, incremental o view.
  • SELECT_STATEMENT: una instrucción SELECT que define la tabla.
  • FILE: el nombre del archivo de definición de la tabla.

En el siguiente código de ejemplo se define una vista en el archivo example SQLX.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

Definir una aserción manual

Almacena las definiciones en la carpeta definitions/.

• Para definir una aserción manual, ejecuta el siguiente comando:

  echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx
  

  Haz los cambios siguientes:

  • SELECT_STATEMENT: una instrucción SELECT que define la aserción.
  • FILE: el nombre del archivo de definición de la operación SQL personalizada.

Definir una operación de SQL personalizada

Almacena las definiciones en la carpeta definitions/.

• Para definir una operación SQL personalizada, ejecuta el siguiente comando:

  echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx
  

  Haz los cambios siguientes:

  • SQL_QUERY: tu operación de SQL personalizada.
  • FILE: el nombre del archivo de definición de la operación SQL personalizada.

Ver la salida de la compilación

Dataform compila tu código en tiempo real.

• Para ver el resultado del proceso de compilación en el terminal, ejecuta el siguiente comando:

  dataform compile
  

• Para ver el resultado del proceso de compilación como un objeto JSON, ejecuta el siguiente comando:

  dataform compile --json
  

• Para ver el resultado de la compilación con variables de compilación personalizadas, ejecute el siguiente comando:

  dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar
  

  Haz los cambios siguientes:

  • SAMPLE_VAR: tu variable de compilación personalizada.
  • SAMPLE_VALUE: el valor de tu variable de compilación personalizada.

Ejecutar código

Para ejecutar tu código, Dataform accede a BigQuery para determinar su estado actual y adaptar el SQL resultante en consecuencia.

• Para ejecutar el código de tu proyecto de Dataform, ejecuta el siguiente comando:

  dataform run
  

• Para ejecutar el código de tu proyecto de Dataform en BigQuery con variables de compilación personalizadas, ejecuta el siguiente comando:

  dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2
  

  Haz los cambios siguientes:

  • SAMPLE_VAR: tu variable de compilación personalizada.
  • SAMPLE_VALUE: el valor de tu variable de compilación personalizada.

• Para ejecutar el código de tu proyecto de Dataform en BigQuery y volver a compilar todas las tablas desde cero, ejecuta el siguiente comando:

  dataform run --full-refresh
  

Sin --full-refresh, Dataform actualiza las tablas incrementales sin tener que volver a crearlas desde cero.

• Para hacer una prueba de funcionamiento de tu código en BigQuery, ejecuta el siguiente comando:

  dataform run --dry-run
  

Nota: En Dataform Core 3.0.2 o versiones posteriores, Dataform realiza una prueba de cada acción de la salida de compilación en BigQuery y requiere los permisos de gestión de identidades y accesos correspondientes. Para verificar la compilación sin hacer una prueba de funcionamiento, consulta el resultado de la compilación.

Obtener ayuda

• Para ver todos los comandos y las opciones disponibles, ejecuta el siguiente comando:

  dataform help
  

• Para ver una descripción de un comando específico, ejecuta el siguiente comando:

  dataform help COMMAND
  

  Sustituye COMMAND por el comando sobre el que quieras obtener información.

Siguientes pasos

• Para obtener más información sobre la CLI de Dataform, consulta la referencia de la CLI de Dataform.
• Para obtener más información sobre Dataform, consulta el resumen de Dataform.