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 poner las credenciales a disposición de tu aplicación en una variedad de entornos, como desarrollo o producción locales, sin necesidad de modificar el código de la aplicación. Para usar ADC, primero debes proporcionar tus credenciales.
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
Inicializa un proyecto de Dataform
Para inicializar un nuevo proyecto de Dataform, ejecuta el siguiente comando dentro del directorio de tu proyecto:
dataform init . PROJECT_NAME DEFAULT_LOCATION
Reemplaza lo siguiente:
- PROJECT_NAME: nombre del proyecto.
- DEFAULT_LOCATION: Es la región en la que deseas que Dataform escriba los datos de BigQuery. Para obtener más información sobre las regiones de BigQuery, consulta Ubicaciones de BigQuery.
Actualizar Dataform
Para actualizar el framework de Dataform, actualiza el
dataformCoreVersion
en el archivoworkflow_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:
Ejecuta el siguiente comando:
dataform init-creds
Sigue el asistente de
init-creds
que te guiará en la creación del archivo de credenciales.
Crea un proyecto
Un proyecto vacío de Dataform en el núcleo de Dataform 3.0.0-beta.0
o versiones posteriores tiene la siguiente estructura:
project-dir
├── definitions
├── includes
└── workflow_settings.yaml
Si quieres crear un proyecto de Dataform para implementar recursos en BigQuery, ejecuta el siguiente comando:
dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID
Reemplaza lo siguiente:
- PROJECT_NAME: nombre del proyecto.
- YOUR_GOOGLE_CLOUD_PROJECT_ID: tu ID del 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 clone el repositorio, ejecuta el siguiente comando dentro del directorio del repositorio clonado:
dataform install
Define una tabla
Almacena 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
oview
. - SELECT_STATEMENT: Es una sentencia
SELECT
que define la tabla. - FILE: Es el nombre del archivo de definición de tablas.
- TABLE_TYPE: Es el tipo de tabla:
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 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 declaración
SELECT
que define la aserción. - FILE: Es el nombre del archivo de definición de la operación de SQL personalizada.
- SELECT_STATEMENT: Es una declaración
Define una operación de SQL personalizada
Almacena 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 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: 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 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: 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 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 ver una lista de 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 información.
¿Qué sigue?
- 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 Descripción general de Dataform.