Usa la CLI de Dataform de código abierto

En este documento, se muestra 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 con la terminal.

Con la CLI de Dataform de código abierto, 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 hacer que las credenciales estén disponibles para tu aplicación en una variedad de entornos, como el desarrollo o producción local, sin necesidad de modificar el código de la aplicación. Para usar ADC, primero debes proporcionar tus credenciales a ADC.

Antes de comenzar

Antes de instalar la CLI de Dataform, instala NPM.

Instala la CLI de Dataform

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

    npm i -g @dataform/cli

Inicializa un proyecto de Dataform

  • Para inicializar un proyecto de Dataform nuevo, ejecuta el siguiente comando dentro del directorio de tu proyecto:

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

    Reemplaza lo siguiente:

    • YOUR_GOOGLE_CLOUD_PROJECT_ID: Es el ID del Google Cloud proyecto.
    • DEFAULT_LOCATION: Es la ubicación de BigQuery en la que deseas que Dataform procese y almacene datos.

Actualiza Dataform core

  • Para actualizar el framework de Dataform core, actualiza dataformCoreVersion en el archivo workflow_settings.yaml. Cuando se establece dataformCoreVersion en workflow_settings.yaml, Dataform instala @dataform/core automáticamente durante el tiempo de ejecución. Si tu proyecto administra @dataform/core en un archivo package.json sin dataformCoreVersion en workflow_settings.yaml, actualiza la versión en package.json y ejecuta lo siguiente:

    dataform install

Actualiza la CLI de Dataform

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

    npm i -g @dataform/cli@^3.0.50

Crea 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.

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 guía por la creación del archivo de credenciales.

Crea un proyecto

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

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

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

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

    Reemplaza lo siguiente:

    • PROJECT_NAME: Es el nombre del directorio de tu proyecto.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: Es el ID del Google Cloud proyecto.
    • DEFAULT_LOCATION: Es la ubicación de BigQuery en la que deseas que Dataform procese y almacene datos.

Clona un proyecto

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

  • Si el proyecto clonado declara dependencias externas en un archivo package.json (sin dataformCoreVersion en workflow_settings.yaml), ejecuta el siguiente comando dentro del directorio del repositorio clonado:

    dataform install

Define 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

    Reemplaza lo siguiente:

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

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

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

Define 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

    Reemplaza lo siguiente:

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

Define una operación de SQL personalizada

Almacena las definiciones en la carpeta definitions/.

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

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

    Reemplaza lo siguiente:

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

Visualiza el resultado de la compilación

Dataform compila tu código en tiempo real.

  • Para ver el resultado del proceso de compilación en la 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, ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • SAMPLE_VAR: Es tu variable de compilación personalizada.
    • SAMPLE_VALUE: Es 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

    Reemplaza lo siguiente:

    • SAMPLE_VAR: Es tu variable de compilación personalizada.
    • SAMPLE_VALUE: Es 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 las tablas incrementales (a menos que estén marcadas como protected) desde cero, ejecuta el siguiente comando:

    dataform run --full-refresh

Sin --full-refresh, Dataform actualiza las tablas incrementales sin volver a compilarlas desde cero (las tablas y vistas normales siempre se vuelven a compilar).

  • Para realizar una ejecución de prueba de tu código en BigQuery, ejecuta el siguiente comando:

    dataform run --dry-run

Obtener ayuda

  • Para enumerar todos los comandos y 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

    Reemplaza COMMAND por el comando sobre el que deseas obtener información.

¿Qué sigue?