Open-Source-Dataform-Befehlszeile verwenden

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

Mit der Open-Source-Dataform-Befehlszeile können Sie den Dataform-Kern lokal außerhalb von Google Cloudinitialisieren, 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.

Hinweis

Bevor Sie die Dataform CLI installieren, müssen Sie NPM installieren.

Dataform-Befehlszeile installieren

  • Führen Sie den folgenden Befehl aus, um die Dataform-Befehlszeile zu installieren:

    npm i -g @dataform/cli@^3.0.0-beta

Dataform-Projekt initialisieren

  • Führen Sie zum Initialisieren eines neuen Dataform-Projekts den folgenden Befehl in Ihrem Projektverzeichnis aus:

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Ersetzen Sie Folgendes:

    • PROJECT_NAME: Name Ihres Projekts
    • DEFAULT_LOCATION: Die Region, in der Dataform BigQuery-Daten schreiben soll. Weitere Informationen zu BigQuery-Regionen finden Sie unter BigQuery-Standorte.

Dataform-Kern aktualisieren

  • Wenn Sie das Dataform-Kernframework aktualisieren möchten, aktualisieren Sie die Datei dataformCoreVersion in workflow_settings.yaml und führen Sie dann NPM install noch einmal aus:

    npm i

Dataform-Befehlszeile aktualisieren

  • Führen Sie den folgenden Befehl aus, um das Dataform-Befehlszeilentool zu aktualisieren:

    npm i -g @dataform/cli@^3.0.0-beta.2

Datei mit Anmeldedaten erstellen

Dataform benötigt eine Anmeldedatendatei, um eine Verbindung zu Remote-Diensten herzustellen und die Datei .df-credentials.json auf Ihrem Laufwerk zu erstellen.

So erstellen Sie die Anmeldedatendatei:

  1. Führen Sie dazu diesen Befehl aus:

    dataform init-creds

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

Projekt erstellen

Ein leeres Dataform-Projekt in Dataform Core 3.0.0-beta.0 oder höher hat 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 Folgendes:

    • PROJECT_NAME: Name Ihres Projekts
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: Ihre Google Cloud Projekt-ID.

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 Bestätigung 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: Ihren benutzerdefinierten 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 folgenden Befehl aus, um die Ausgabe des Kompilierungsprozesses als JSON-Objekt aufzurufen:

    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: den Wert Ihrer benutzerdefinierten Kompilierungsvariablen.

Code ausführen

Um Ihren Code auszuführen, greift Dataform auf BigQuery zu, um den aktuellen Status 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

  • 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: den Wert Ihrer benutzerdefinierten Kompilierungsvariablen.

  • Wenn Sie den Code Ihres Dataform-Projekts in BigQuery ausführen und alle Tabellen neu erstellen möchten, führen Sie den folgenden Befehl aus:

    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 einen Probelauf Ihres Codes in 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