Open-Source-Dataform-CLI verwenden

In diesem Dokument erfahren Sie, wie Sie mit der Open-Source-Befehlszeile von Dataform SQL-Workflows lokal über das Terminal entwickeln können.

Mit der Open-Source-Dataform-CLI können Sie Dataform Core lokal außerhalb von Google Cloud initialisieren, kompilieren, testen und ausführen.

Dataform verteilt ein Docker-Image, mit dem Sie das Äquivalent der Dataform-Befehlszeilenbefehle ausführen können.

Die Dataform-Befehlszeile unterstützt Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). Mit ADC können Sie Anmeldedaten für Ihre Anwendung in verschiedenen Umgebungen zur Verfügung stellen, z. B. in der lokalen Entwicklung oder Produktion, ohne Ihren Anwendungscode ändern zu müssen. Wenn Sie ADC verwenden möchten, müssen Sie zuerst Ihre Anmeldedaten für ADC angeben.

Hinweise

Installieren Sie NPM, bevor Sie die Dataform CLI installieren.

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

Dataform-Projekt initialisieren

  • Führen Sie den folgenden Befehl in Ihrem Projektverzeichnis aus, um ein neues Dataform-Projekt zu initialisieren:

    dataform init

Dataform aktualisieren

  • Wenn Sie das Dataform-Framework aktualisieren möchten, aktualisieren Sie die Datei 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 Remotediensten herzustellen und die Datei .df-credentials.json auf Ihrem Laufwerk zu erstellen.

So erstellen Sie eine Datei mit den Anmeldedaten:

  1. Führen Sie dazu diesen Befehl aus:

    dataform init-creds

  2. Folgen Sie dem init-creds-Assistenten, der Sie durch die Erstellung der Datei mit Anmeldedaten führt.

Projekt erstellen

Ein leeres Dataform-Projekt 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-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Ersetzen Sie PROJECT_NAME durch den Namen Ihres Projekts und YOUR_GOOGLE_CLOUD_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

Projekt klonen

Folgen Sie der Anleitung Ihres Git-Anbieters, um ein vorhandenes Dataform-Projekt aus einem Git-Repository eines Drittanbieters zu klonen.

  • Führen Sie nach dem Klonen des Repositorys den folgenden Befehl im geklonten Repository-Verzeichnis aus:

    dataform install

Tabelle definieren

Speichert 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 durch den Typ der Tabelle: table, incremental oder view.
    • SELECT_STATEMENT durch eine SELECT-Anweisung, die die Tabelle definiert.
    • FILE durch den Namen 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 Assertion definieren

Speichert Definitionen im Ordner definitions/.

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

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

    Ersetzen Sie Folgendes:

    • SELECT_STATEMENT durch eine SELECT-Anweisung, die die Assertion definiert.
    • FILE durch den Namen der benutzerdefinierten SQL-Vorgangsdefinitionsdatei.

Benutzerdefinierten SQL-Vorgang definieren

Speichert 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 durch Ihren benutzerdefinierten SQL-Vorgang.
    • FILE durch den Namen der benutzerdefinierten SQL-Vorgangsdefinitionsdatei.

Kompilierungsausgabe ansehen

Dataform kompiliert Ihren Code in Echtzeit.

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

    dataform compile

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

    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 durch Ihre benutzerdefinierte Kompilierungsvariable.
    • SAMPLE_VALUE durch den Wert Ihrer benutzerdefinierten Kompilierungsvariable.

Code ausführen

Zum Ausführen des Codes greift Dataform auf BigQuery zu, um seinen aktuellen Zustand zu ermitteln und die resultierende SQL-Abfrage entsprechend anzupassen.

  • Führen Sie den folgenden Befehl aus, um den Code Ihres Dataform-Projekts auszuführen:

    dataform run

  • Führen Sie den folgenden Befehl aus, um den Code Ihres Dataform-Projekts in BigQuery mit benutzerdefinierten Kompilierungsvariablen auszuführen:

    dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2

    Ersetzen Sie Folgendes:

    • SAMPLE_VAR durch Ihre benutzerdefinierte Kompilierungsvariable.
    • SAMPLE_VALUE durch den Wert Ihrer benutzerdefinierten Kompilierungsvariable.

  • Führen Sie den folgenden Befehl aus, um den Code Ihres Dataform-Projekts in BigQuery auszuführen und alle Tabellen von Grund auf neu zu erstellen:

    dataform run --full-refresh

Ohne --full-refresh aktualisiert Dataform inkrementelle Tabellen, ohne sie von Grund auf neu zu erstellen.

  • Führen Sie den folgenden Befehl aus, um den endgültigen kompilierten SQL-Code anzuzeigen, der auf den aktuellen Status von BigQuery zugeschnitten ist, ohne ihn in BigQuery auszufü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 die Beschreibung eines bestimmten Befehls abzurufen:

    dataform help COMMAND

    Ersetzen Sie COMMAND durch den Befehl, über den Sie mehr erfahren möchten.

Nächste Schritte