Open-Source-Dataform-CLI verwenden

In diesem Dokument erfahren Sie, wie Sie die Open-Source-Befehlszeilenschnittstelle Dataform (CLI) verwenden, um SQL-Workflows mithilfe des Terminals lokal zu entwickeln.

Mit der Open-Source-Dataform-Befehlszeile 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 zu Dataform-CLI-Befehlen ausführen können.

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

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

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: Die Region, in die Dataform BigQuery-Daten schreiben soll. Weitere Informationen zu BigQuery-Regionen finden Sie unter BigQuery-Standorte.

Dataform aktualisieren

  • Aktualisieren Sie zum Aktualisieren des Dataform-Frameworks 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 die 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 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-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Ersetzen Sie Folgendes:

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

Projekt klonen

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

  • Nachdem das Repository geklont wurde, führen Sie im geklonten Repository-Verzeichnis den folgenden Befehl aus:

    dataform install

Tabelle definieren

Definitionen werden im Ordner definitions/ gespeichert.

  • 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 Tabellentyp 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 Assertion definieren

Definitionen werden im Ordner definitions/ gespeichert.

  • 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: Eine SELECT-Anweisung, die die Assertion definiert.
    • FILE: der Name der Definitionsdatei für benutzerdefinierte SQL-Vorgänge.

Benutzerdefinierten SQL-Vorgang definieren

Definitionen werden im Ordner definitions/ gespeichert.

  • 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 Definitionsdatei für benutzerdefinierte SQL-Vorgänge.

Kompilierungsausgabe ansehen

Dataform kompiliert Ihren Code in Echtzeit.

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

    dataform compile

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

    dataform compile --json

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

    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

Zum Ausführen des Codes greift Dataform auf BigQuery zu, um den aktuellen Status zu ermitteln und das resultierende SQL 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: Ihre benutzerdefinierte Kompilierungsvariable.
    • SAMPLE_VALUE: der 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 zu sehen, 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 eine Beschreibung eines bestimmten Befehls anzuzeigen:

    dataform help COMMAND

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

Nächste Schritte