Open-Source-Dataform-Befehlszeile verwenden

In diesem Dokument wird beschrieben, 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: Ab Dataform Core 3.0.0., wird kein Docker-Image mehr von Dataform bereitgestellt. Sie können Ihr eigenes Docker-Image von Dataform erstellen, mit dem Sie das Äquivalent von Dataform CLI-Befehlen ausführen können. Informationen zum Erstellen eines eigenen Docker-Images finden Sie in der Docker-Dokumentation unter Containerisieren einer Anwendung.

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
  

Hinweis: Version 3.0.0-beta wird nicht unterstützt. Wenn npm audit eine schwerwiegende Sicherheitslücke im Zusammenhang mit dem vm2-Paket meldet, verwendet Dataform zwar vm2, aber nicht für das Sandboxing, das die Quelle der gemeldeten Sicherheitslücken ist.vm2 Neuere Versionen der Dataform CLI sind nicht von anfälligen vm2-Versionen abhängig.

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 Standort, an dem Dataform BigQuery-Daten schreiben soll. Wenn nicht festgelegt, bestimmt Dataform den Standort anhand der Datasets, auf die sich Ihre SQL-Abfrage bezieht. Das funktioniert so:

    • Wenn Ihre Abfrage auf Datasets vom selben Standort verweist, verwendet Dataform diesen Standort.
    • Wenn Ihre Abfrage auf Datasets von zwei oder mehr verschiedenen Standorten verweist, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
    • Wenn Ihre Abfrage auf keine Datasets verweist, ist der Standardspeicherort für Dataform die Multiregion US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den Standardspeicherort fest. Alternativ können Sie die @@location Systemvariable 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 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.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.

Warnung:Wenn Sie ein Quellverwaltungssystem verwenden, übertragen Sie die Datei .df-credentials.json nicht in Ihr Repository, um diese Anmeldedaten zu schützen. Wir empfehlen, die Datei .df-credentials.json zu .gitignore hinzuzufügen.

So erstellen Sie die Datei mit Anmeldedaten:

1. Führen Sie dazu diesen Befehl aus:

   dataform init-creds
   

2. Folgen Sie der Anleitung des 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 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: Projekt-ID in Google Cloud .

  • DEFAULT_LOCATION (optional): der Standort, an dem Dataform BigQuery-Daten schreiben soll. Wenn nicht festgelegt, bestimmt Dataform den Standort anhand der Datasets, auf die sich Ihre SQL-Abfrage bezieht. Das funktioniert so:

    • Wenn Ihre Abfrage auf Datasets vom selben Standort verweist, verwendet Dataform diesen Standort.
    • Wenn Ihre Abfrage auf Datasets von zwei oder mehr verschiedenen Standorten verweist, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
    • Wenn Ihre Abfrage auf keine Datasets verweist, ist der Standardspeicherort für Dataform die Multiregion US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den Standardspeicherort fest. Alternativ können Sie die @@location Systemvariable 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 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 benutzerdefinierte SQL-Vorgänge.

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 benutzerdefinierte SQL-Vorgänge.

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 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 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 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 einen Probelauf Ihres Codes in BigQuery durchzuführen:

  dataform run --dry-run
  

Hinweis: In Dataform Core 3.0.2 oder höher führt Dataform einen Probelauf jeder Aktion in Ihrer Kompilierungsausgabe in BigQuery durch und erfordert die entsprechenden IAM-Berechtigungen. Wenn Sie die Kompilierung ohne Probelauf überprüfen möchten, sehen Sie sich die Kompilierungsausgabe an.

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

• Weitere Informationen zur Dataform CLI finden Sie in der Dataform CLI-Referenz
• Weitere Informationen zu Dataform finden Sie in der Dataform-Übersicht.