Usa la CLI de código abierto de Dataform

En este documento, se muestra cómo usar la interfaz de línea de comandos (CLI) de Dataform de código abierto para desarrollar flujos de trabajo de SQL 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.

Dataform distribuye una imagen de Docker que puedes usar para ejecutar el equivalente a los comandos de la CLI de Dataform.

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 desarrollo o producción local, sin necesidad de modificar el código de tu 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@^3.0.0-beta.2

Inicializa un proyecto de Dataform

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

    dataform init

Actualizar Dataform

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

    npm i

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.0-beta.2

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 de init-creds que te guiará en la creación de archivos de credenciales.

Crea un proyecto

Un proyecto vacío de Dataform tiene la siguiente estructura:

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

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

    dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Reemplaza PROJECT_NAME por el nombre de tu proyecto y YOUR_GOOGLE_CLOUD_PROJECT_ID por el ID de tu proyecto de Google Cloud.

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.

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

    dataform install

Cómo 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

    Reemplaza lo siguiente:

    • TABLE_TYPE por el tipo de la tabla: table, incremental o view
    • SELECT_STATEMENT con una declaración SELECT que define la tabla.
    • FILE por 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 con una declaración SELECT que define la aserción.
    • FILE por el nombre del archivo de definición de la operación de SQL personalizada

Cómo definir 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 por la operación de SQL personalizada.
    • FILE por el nombre del archivo de definición de la operación de SQL personalizada

Ver 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 por tu variable de compilación personalizada
    • SAMPLE_VALUE por el valor de la variable de compilación personalizada

Ejecutar código

Para ejecutar tu código, Dataform accede a BigQuery con el objetivo de determinar su estado actual y adaptar el SQL resultante según corresponda.

  • 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 por tu variable de compilación personalizada
    • SAMPLE_VALUE por el valor de la 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 volver a compilarlas desde cero.

  • Para ver el código SQL compilado final adaptado al estado actual de BigQuery, sin ejecutarlo dentro de 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 la descripción de un comando específico, ejecuta el siguiente comando:

    dataform help COMMAND

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

¿Qué sigue?