Open-Source-Dataform-Befehlszeile verwenden

In diesem Dokument erfahren Sie, wie Sie die Open-Source-Befehlszeilenschnittstelle (Command-Line Interface, CLI) von Dataform verwenden, um Workflows lokal über das Terminal zu entwickeln.

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

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

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

Dataform-Projekt initialisieren

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

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

    Ersetzen Sie Folgendes:

    • YOUR_GOOGLE_CLOUD_PROJECT_ID: Projekt-ID in Google Cloud .
    • DEFAULT_LOCATION: der BigQuery-Standort, an dem Dataform Daten verarbeiten und speichern soll.

Dataform Core aktualisieren

  • Wenn Sie das Dataform Core-Framework aktualisieren möchten, aktualisieren Sie dataformCoreVersion in der Datei workflow_settings.yaml. Wenn dataformCoreVersion in workflow_settings.yaml festgelegt ist, installiert Dataform @dataform/core automatisch zur Laufzeit. Wenn Ihr Projekt stattdessen @dataform/core in einer package.json-Datei ohne dataformCoreVersion in workflow_settings.yaml verwaltet, aktualisieren Sie die Version in package.json und führen Sie Folgendes aus:

    dataform install

Dataform CLI aktualisieren

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

    npm i -g @dataform/cli@^3.0.50

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 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 Anmeldedaten führt.

Projekt erstellen

Ein leeres Dataform-Projekt in Dataform Core 3.0.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 zu erstellen, mit dem Assets in BigQuery bereitgestellt werden können:

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

    Ersetzen Sie Folgendes:

    • PROJECT_NAME: der Verzeichnisname Ihres Projekts.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: Projekt-ID in Google Cloud .
    • DEFAULT_LOCATION: der BigQuery-Standort, an dem Sie Dataform Daten verarbeiten und speichern sollen.

Projekt klonen

Wenn Sie ein vorhandenes Dataform-Projekt aus einem Git-Repository eines Drittanbieters klonen möchten, folgen Sie der Anleitung Ihres Git-Anbieters.

  • Wenn das geklonte Projekt externe Abhängigkeiten in einer package.json-Datei deklariert (ohne dataformCoreVersion in workflow_settings.yaml), führen Sie 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 Assertion definieren

Speichern Sie 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: eine SELECT-Anweisung, die die Assertion definiert.
    • FILE: der Name der Definitionsdatei für den benutzerdefinierten SQL-Vorgang.

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 Definitionsdatei für den benutzerdefinierten SQL-Vorgang.

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

Um Ihren Code auszuführen, 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

  • Führen Sie den folgenden Befehl aus, um den Code Ihres Dataform-Projekts in BigQuery mit benutzerdefinierten Kompilierungsvariablenauszufü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 inkrementelle Tabellen (sofern nicht als protected gekennzeichnet) 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 (reguläre Tabellen und Ansichten werden immer neu erstellt).

  • 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