Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
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@^3.0.0-beta
Inicializa un proyecto de Dataform
Para inicializar un proyecto de Dataform nuevo, ejecuta el siguiente comando dentro del directorio de tu proyecto:
dataform init . PROJECT_NAMEDEFAULT_LOCATION
Reemplaza lo siguiente:
PROJECT_NAME: nombre del proyecto.
DEFAULT_LOCATION (opcional): Es la ubicación en la que deseas que Dataform escriba los datos de BigQuery. 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. 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 producirá 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 otra ubicación, 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.
Actualiza Dataform Core
Para actualizar el framework principal de Dataform, actualiza 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 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 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-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 se implementarán recursos en BigQuery, ejecuta el siguiente comando:
YOUR_GOOGLE_CLOUD_PROJECT_ID: El ID de tu proyecto de Google Cloud .
DEFAULT_LOCATION (opcional): Es la ubicación en la que deseas que Dataform escriba los datos de BigQuery. 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. 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 producirá 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 otra ubicación, 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.
Clona un proyecto
Para clonar un proyecto de Dataform existente desde un repositorio de Git externo, 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
Cómo definir una tabla
Almacena las definiciones en la carpeta definitions/.
Para definir una tabla, ejecuta el siguiente comando:
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (UTC)"],[[["\u003cp\u003eThe Dataform CLI allows for local development of SQL workflows, enabling users to initialize, compile, test, and run Dataform core outside of Google Cloud.\u003c/p\u003e\n"],["\u003cp\u003eThe Dataform CLI supports Application Default Credentials (ADC) for managing credentials across different environments without code modification.\u003c/p\u003e\n"],["\u003cp\u003eDataform projects can be initialized, cloned, and managed locally, and the CLI provides commands to define tables, manual assertions, and custom SQL operations.\u003c/p\u003e\n"],["\u003cp\u003eUsers can compile code and view the output in real-time, either in the terminal or as a JSON object, including options for custom compilation variables.\u003c/p\u003e\n"],["\u003cp\u003eThe CLI facilitates code execution, dry runs, and full refreshes in BigQuery, with commands available to get help on specific command options.\u003c/p\u003e\n"]]],[],null,["# Use the open-source Dataform CLI\n\nThis document shows you how to use the open-source Dataform command-line interface (CLI) to locally develop workflows by using the terminal.\n\n\u003cbr /\u003e\n\nWith the open-source Dataform CLI, you can initialize, compile, test,\nand run [Dataform core](/dataform/docs/overview#dataform-core) locally,\noutside of Google Cloud.\n\nThe Dataform CLI supports [Application Default Credentials (ADC)](/docs/authentication/application-default-credentials).\nWith ADC, you can make credentials available to your application in a variety\nof environments, such as local development or production, without needing to\nmodify your application code. To use ADC, you must first\n[provide your credentials](/docs/authentication/provide-credentials-adc) to ADC.\n| **Note:** As of [Dataform core `3.0.0.`](https://github.com/dataform-co/dataform/releases/tag/3.0.0), Dataform doesn't distribute a Docker image. You can build your own Docker image of Dataform, which you can use to run the equivalent of Dataform CLI commands. To build your own Docker image, see [Containerize an application](https://docs.docker.com/guides/workshop/02_our_app/) in the Docker documentation.\n\nBefore you begin\n----------------\n\nBefore installing the Dataform CLI, install\n[NPM](https://www.npmjs.com/get-npm).\n\nInstall Dataform CLI\n--------------------\n\n- To install Dataform CLI, run the following command:\n\n npm i -g @dataform/cli@^3.0.0-beta\n\nInitialize a Dataform project\n-----------------------------\n\n- To initialize a new Dataform project,\n run the following command inside your project directory:\n\n dataform init . \u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e \u003cvar translate=\"no\"\u003eDEFAULT_LOCATION\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e: the name of your project.\n - \u003cvar translate=\"no\"\u003eDEFAULT_LOCATION\u003c/var\u003e: the region where you want Dataform to write BigQuery data. For more information about BigQuery regions, see [BigQuery locations](/bigquery/docs/locations).\n\nUpdate Dataform core\n--------------------\n\n- To update the Dataform core framework, update the `dataformCoreVersion`\n in `workflow_settings.yaml` file, then re-run NPM install:\n\n npm i\n\nUpdate Dataform CLI\n-------------------\n\n- To update the Dataform CLI tool, run the following command:\n\n npm i -g @dataform/cli@^3.0.0-beta.2\n\nCreate a credentials file\n-------------------------\n\nDataform requires a credentials file to connect to remote services\nand create the `.df-credentials.json` file on your disk.\n| **Warning:** If you use a source control system, don't commit the `df-credentials.json`. file to your repository to protect these access credentials. We recommend that you add the `.df-credentials.json` file to `.gitignore`.\n\nTo create the credentials file, follow these steps:\n\n1. Run the following command:\n\n dataform init-creds\n\n2. Follow the `init-creds` wizard that walks you through credentials file creation.\n\nCreate a project\n----------------\n\nAn empty Dataform project in Dataform core `3.0.0-beta.0`\nor later has the following structure: \n\n project-dir\n ├── definitions\n ├── includes\n └── workflow_settings.yaml\n\n- To create a Dataform project to deploy assets to BigQuery,\n run the following command:\n\n dataform init \u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e --default-database \u003cvar translate=\"no\"\u003eYOUR_GOOGLE_CLOUD_PROJECT_ID\u003c/var\u003e --default-location \u003cvar translate=\"no\"\u003eDEFAULT_LOCATION\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e: the name of your project.\n - \u003cvar translate=\"no\"\u003eYOUR_GOOGLE_CLOUD_PROJECT_ID\u003c/var\u003e: your Google Cloud project ID.\n - \u003cvar translate=\"no\"\u003eDEFAULT_LOCATION\u003c/var\u003e: the region where you want Dataform to write BigQuery data. For more information about BigQuery regions, see [BigQuery locations](/bigquery/docs/locations).\n\nClone a project\n---------------\n\nTo clone an existing Dataform project from a third-party Git repository,\nfollow the instructions from your Git provider.\n\n- Once the repository is cloned, run the following command inside\n the cloned repository directory:\n\n dataform install\n\nDefine a table\n--------------\n\nStore definitions in the `definitions/` folder.\n\n- To define a table, run the following command:\n\n echo \"config { type: '\u003cvar translate=\"no\"\u003eTABLE_TYPE\u003c/var\u003e' } \u003cvar translate=\"no\"\u003eSELECT_STATEMENT\u003c/var\u003e\" \u003e definitions/\u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e.sqlx\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eTABLE_TYPE\u003c/var\u003e: the type of the table: `table`, `incremental`, or `view`.\n - \u003cvar translate=\"no\"\u003eSELECT_STATEMENT\u003c/var\u003e: a `SELECT` statement that defines the table.\n - \u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e: the name for the table definition file.\n\nThe following code sample defines a view in the `example` SQLX file. \n\n echo \"config { type: 'view' } SELECT 1 AS test\" \u003e definitions/example.sqlx\n\nDefine a manual assertion\n-------------------------\n\nStore definitions in the `definitions/` folder.\n\n- To define a manual assertion, run the following command:\n\n echo \"config { type: 'assertion' } \u003cvar translate=\"no\"\u003eSELECT_STATEMENT\u003c/var\u003e\" \u003e definitions/\u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e.sqlx\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSELECT_STATEMENT\u003c/var\u003e: a `SELECT` statement that defines the assertion.\n - \u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e: the name for the custom SQL operation definition file.\n\nDefine a custom SQL operation\n-----------------------------\n\nStore definitions in the `definitions/` folder.\n\n- To define a custom SQL operation, run the following command:\n\n echo \"config { type: 'operations' } \u003cvar translate=\"no\"\u003eSQL_QUERY\u003c/var\u003e\" \u003e definitions/\u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e.sqlx\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSQL_QUERY\u003c/var\u003e: your custom SQL operation.\n - \u003cvar translate=\"no\"\u003eFILE\u003c/var\u003e: the name for the custom SQL operation definition file.\n\nView compilation output\n-----------------------\n\nDataform compiles your code in real time.\n\n- To view the output of the compilation process in the terminal,\n run the following command:\n\n dataform compile\n\n- To view the output of the compilation process as a JSON object,\n run the following command:\n\n dataform compile --json\n\n- To view the output of the compilation with\n [custom compilation variables](/dataform/docs/configure-execution),\n run the following command:\n\n dataform compile --vars=\u003cvar translate=\"no\"\u003eSAMPLE_VAR\u003c/var\u003e=\u003cvar translate=\"no\"\u003eSAMPLE_VALUE\u003c/var\u003e,foo=bar\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSAMPLE_VAR\u003c/var\u003e: your custom compilation variable.\n - \u003cvar translate=\"no\"\u003eSAMPLE_VALUE\u003c/var\u003e: the value of your custom compilation variable.\n\nRun code\n--------\n\nTo run your code, Dataform accesses BigQuery to\ndetermine its current state and tailor the resulting SQL accordingly.\n\n- To run the code of your Dataform project, run the following command:\n\n dataform run\n\n- To run the code of your Dataform project in BigQuery\n with [custom compilation variables](/dataform/docs/configure-execution),\n run the following command:\n\n dataform run --vars=\u003cvar translate=\"no\"\u003eSAMPLE_VAR\u003c/var\u003e=\u003cvar translate=\"no\"\u003eSAMPLE_VALUE\u003c/var\u003e,sampleVar2=sampleValue2\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSAMPLE_VAR\u003c/var\u003e: your custom compilation variable.\n - \u003cvar translate=\"no\"\u003eSAMPLE_VALUE\u003c/var\u003e: the value of your custom compilation variable.\n- To run the code of your Dataform project in BigQuery\n and rebuild all tables from scratch, run the following command:\n\n dataform run --full-refresh\n\nWithout `--full-refresh`, Dataform updates incremental tables\nwithout rebuilding them from scratch.\n\n- To perform a dry run of your code against BigQuery,\n run the following command:\n\n dataform run --dry-run\n\n| **Note:** In Dataform core `3.0.2` or later, Dataform performs a dry run of each action in your compilation output against BigQuery, and requires corresponding IAM permissions. To verify compilation without a dry run, [view compilation output](#view_compilation_output).\n\nGet help\n--------\n\n- To list all of the available commands and options,\n run the following command:\n\n dataform help\n\n- To view a description of a specific command,\n run the following command:\n\n dataform help \u003cvar translate=\"no\"\u003eCOMMAND\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003eCOMMAND\u003c/var\u003e with the command you want to learn about.\n\nWhat's next\n-----------\n\n- To learn more about Dataform CLI, see [Dataform CLI reference](/dataform/docs/reference/dataform-cli-reference)\n- To learn more about Dataform, see [Dataform overview](/dataform/docs/overview)."]]
