Open-Source-Dataform-Befehlszeile verwenden

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.

Die Dataform CLI unterstützt Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). Mit ADC können Sie Anmeldedaten für Ihre Anwendung in verschiedenen Umgebungen bereitstellen, z. B. in der lokalen Entwicklung oder Produktion, ohne den Anwendungscode ändern zu müssen. Wenn Sie ADC verwenden möchten, müssen Sie zuerst Ihre Anmeldedaten gegenüber ADC angeben.

Hinweise

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_NAME DEFAULT_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:

  1. Führen Sie dazu diesen Befehl aus:

    dataform init-creds

  2. 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:

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

    Ersetzen Sie Folgendes:

    • PROJECT_NAME: Name Ihres Projekts
    • 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:

    echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Ersetzen Sie Folgendes:

    • TABLE_TYPE: Der Typ der Tabelle: table, incremental oder view.
    • SELECT_STATEMENT: Eine SELECT-Anweisung, die die Tabelle definiert.
    • FILE: der Name der Tabellendefinitionsdatei.

Im folgenden Codebeispiel wird eine Ansicht in der SQLX-Datei example definiert.

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

Manuelle Behauptung definieren

Speichern Sie Definitionen im Ordner definitions/.

  • Führen Sie den folgenden Befehl aus, um eine manuelle Behauptung zu definieren:

    echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Ersetzen Sie Folgendes:

    • SELECT_STATEMENT: Eine SELECT-Anweisung, die die Behauptung definiert.
    • FILE: Der Name der Datei mit der Definition des benutzerdefinierten SQL-Vorgangs.

Benutzerdefinierten SQL-Vorgang definieren

Speichern Sie Definitionen im Ordner definitions/.

  • Führen Sie den folgenden Befehl aus, um einen benutzerdefinierten SQL-Vorgang zu definieren:

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

    Ersetzen Sie Folgendes:

    • SQL_QUERY: Ihr benutzerdefinierter SQL-Vorgang.
    • FILE: Der Name der Datei mit der Definition des benutzerdefinierten SQL-Vorgangs.

Kompilierungsausgabe ansehen

Dataform kompiliert Ihren Code in Echtzeit.

  • Führen Sie den folgenden Befehl aus, um die Ausgabe des Kompilierungsprozesses im Terminal aufzurufen:

    dataform compile

  • Führen Sie den folgenden Befehl aus, um die Ausgabe des Kompilierungsprozesses als JSON-Objekt anzuzeigen:

    dataform compile --json

  • Führen Sie den folgenden Befehl aus, um die Ausgabe der Kompilierung mit benutzerdefinierten Kompilierungsvariablen aufzurufen:

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

    Ersetzen Sie Folgendes:

    • 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

  • Wenn Sie den Code Ihres Dataform-Projekts in BigQuery mit benutzerdefinierten Kompilierungsvariablen ausführen möchten, führen Sie den folgenden Befehl aus:

    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.

Nächste Schritte