Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
In diesem Dokument erfahren Sie, wie Sie mit der Open-Source-Befehlszeile (Command-Line Interface, CLI) von Dataform Workflows lokal über das Terminal entwickeln.
Mit der Open-Source-Dataform CLI können Sie Dataform Core lokal, außerhalb von Google Cloud, initialisieren, kompilieren, testen und ausführen.
Bevor Sie die Dataform CLI installieren, installieren Sie NPM.
Dataform CLI installieren
Führen Sie den folgenden Befehl aus, um die Dataform CLI zu installieren:
npm i -g @dataform/cli@^3.0.0-beta
Dataform-Projekt initialisieren
Führen Sie den folgenden Befehl in Ihrem Projektverzeichnis aus, um ein neues Dataform-Projekt zu initialisieren:
dataform init . PROJECT_NAMEDEFAULT_LOCATION
Ersetzen Sie Folgendes:
PROJECT_NAME: Name Ihres Projekts
DEFAULT_LOCATION (optional): Der Speicherort, an dem Dataform BigQuery-Daten schreiben soll. Wenn nicht festgelegt, bestimmt Dataform den Speicherort anhand der Datasets, auf die in Ihrer SQL-Abfrage verwiesen wird. Das funktioniert so:
Wenn in Ihrer Abfrage auf Datasets am selben Standort verwiesen wird, verwendet Dataform diesen Standort.
Wenn Ihre Abfrage auf Datasets aus zwei oder mehr verschiedenen Standorten verweist, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
Wenn in Ihrer Abfrage nicht auf Datasets verwiesen wird, ist der Standardspeicherort für Dataform die Multi-Region US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den Standardstandort fest. Alternativ können Sie die Systemvariable @@location in Ihrer Abfrage verwenden. Weitere Informationen finden Sie unter Standorte angeben.
Dataform Core aktualisieren
Wenn Sie das Dataform Core-Framework aktualisieren möchten, aktualisieren Sie dataformCoreVersion in der Datei workflow_settings.yaml und führen Sie dann die NPM-Installation noch einmal aus:
npm i
Dataform-CLI aktualisieren
Führen Sie den folgenden Befehl aus, um das Dataform CLI-Tool zu aktualisieren:
npm i -g @dataform/cli@^3.0.0-beta.2
Datei mit Anmeldedaten erstellen
Dataform benötigt eine Datei mit Anmeldedaten, um eine Verbindung zu Remote-Diensten herzustellen und die Datei .df-credentials.json auf Ihrer Festplatte zu erstellen.
So erstellen Sie die Datei mit den Anmeldedaten:
Führen Sie dazu diesen Befehl aus:
dataform init-creds
Folgen Sie dem Assistenten init-creds, der Sie durch die Erstellung der Datei mit den Anmeldedaten führt.
Projekt erstellen
Ein leeres Dataform-Projekt in Dataform Core 3.0.0-beta.0 oder höher hat die folgende Struktur:
project-dir
├── definitions
├── includes
└── workflow_settings.yaml
Führen Sie den folgenden Befehl aus, um ein Dataform-Projekt zum Bereitstellen von Assets in BigQuery zu erstellen:
YOUR_GOOGLE_CLOUD_PROJECT_ID: Ihre Google Cloud -Projekt-ID
DEFAULT_LOCATION (optional): Der Speicherort, an dem Dataform BigQuery-Daten schreiben soll. Wenn nicht festgelegt, bestimmt Dataform den Speicherort anhand der Datasets, auf die in Ihrer SQL-Abfrage verwiesen wird. Das funktioniert so:
Wenn in Ihrer Abfrage auf Datasets am selben Standort verwiesen wird, verwendet Dataform diesen Standort.
Wenn Ihre Abfrage auf Datasets aus zwei oder mehr verschiedenen Standorten verweist, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
Wenn in Ihrer Abfrage nicht auf Datasets verwiesen wird, ist der Standardspeicherort für Dataform die Multi-Region US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den Standardstandort fest. Alternativ können Sie die Systemvariable @@location in Ihrer Abfrage verwenden. Weitere Informationen finden Sie unter Standorte angeben.
Projekt klonen
Wenn Sie ein vorhandenes Dataform-Projekt aus einem Git-Repository eines Drittanbieters klonen möchten, folgen Sie der Anleitung Ihres Git-Anbieters.
Führen Sie nach dem Klonen des Repositorys den folgenden Befehl im Verzeichnis des geklonten Repositorys aus:
dataform install
Tabelle definieren
Speichern Sie Definitionen im Ordner definitions/.
Führen Sie den folgenden Befehl aus, um eine Tabelle zu definieren:
SAMPLE_VAR: Ihre benutzerdefinierte Kompilierungsvariable.
SAMPLE_VALUE: Der Wert Ihrer benutzerdefinierten Kompilierungsvariable.
Code ausführen
Damit Ihr Code ausgeführt werden kann, greift Dataform auf BigQuery zu, um den aktuellen Status zu ermitteln und den resultierenden SQL-Code entsprechend anzupassen.
Führen Sie den folgenden Befehl aus, um den Code Ihres Dataform-Projekts auszuführen:
dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2
Ersetzen Sie Folgendes:
SAMPLE_VAR: Ihre benutzerdefinierte Kompilierungsvariable.
SAMPLE_VALUE: Der Wert Ihrer benutzerdefinierten Kompilierungsvariable.
Wenn Sie den Code Ihres Dataform-Projekts in BigQuery ausführen und alle Tabellen von Grund auf neu erstellen möchten, führen Sie den folgenden Befehl aus:
dataform run --full-refresh
Ohne --full-refresh werden inkrementelle Tabellen in Dataform aktualisiert, ohne dass sie von Grund auf neu erstellt werden.
Führen Sie den folgenden Befehl aus, um einen Probelauf Ihres Codes für BigQuery durchzuführen:
dataform run --dry-run
Hilfe
Führen Sie den folgenden Befehl aus, um alle verfügbaren Befehle und Optionen aufzulisten:
dataform help
Führen Sie den folgenden Befehl aus, um eine Beschreibung eines bestimmten Befehls aufzurufen:
dataform help COMMAND
Ersetzen Sie COMMAND durch den Befehl, über den Sie mehr erfahren möchten.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 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,["This 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\nBefore installing the Dataform CLI, install\n[NPM](https://www.npmjs.com/get-npm).\n\nInstall Dataform CLI\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- 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 (optional): the location where\n you want Dataform to write BigQuery data. If unset,\n Dataform determines the location based on the datasets that\n your SQL query references. This works as follows:\n\n - If your query references datasets from the same location, Dataform uses that location.\n - If your query references datasets from two or more different locations, an error occurs. For details about this limitation, see [Cross-region dataset replication](/bigquery/docs/data-replication).\n - If your query doesn't reference any datasets, the default location for Dataform is the `US` multi-region. To choose a different location, set the default location. Alternatively, use the [`@@location` system variable](/bigquery/docs/reference/system-variables) in your query. For more information, see [Specify locations](/bigquery/docs/locations#specify_locations).\n\nUpdate Dataform core\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- 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\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\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\n BigQuery, 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 (optional): the location where you\n want Dataform to write BigQuery data. If unset,\n Dataform determines the location based on the datasets that\n your SQL query references. This works as follows:\n\n - If your query references datasets from the same location, Dataform uses that location.\n - If your query references datasets from two or more different locations, an error occurs. For details about this limitation, see [Cross-region dataset replication](/bigquery/docs/data-replication).\n - If your query doesn't reference any datasets, the default location for Dataform is the `US` multi-region. To choose a different location, set the default location. Alternatively, use the [`@@location` system variable](/bigquery/docs/reference/system-variables) in your query. For more information, see [Specify locations](/bigquery/docs/locations#specify_locations).\n\nClone a project\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\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\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\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\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-compilation#compilation-variables),\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\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-compilation#compilation-variables),\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- 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- 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)."]]
