Dataform-SQL-Workflows mit JavaScript erstellen

In diesem Dokument erfahren Sie, wie Sie mit JavaScript SQL-Workflow-Elemente in Dataform erstellen. Möglicherweise möchten Sie JavaScript über Dataform Core verwenden, um ähnliche Elemente wiederholt in Ihrem Workflow zu erstellen.

Entwickeln von Workflows in Dataform mit JavaScript

Mit Dataform Core können Sie SQL-Workflowaktionen mit SQLX und JavaScript erstellen. Mit JavaScript können Sie ähnliche Aktionen wiederholt in Ihrem Workflow erstellen. So lässt sich beispielsweise eine Ansicht jeder Tabelle in Ihrem Workflow erstellen, aus der bestimmte Nutzer-IDs entfernt werden.

Mit dem folgenden JavaScript-Codebeispiel können Sie eine Ansicht jeder Tabelle erstellen, in der der Wert des Felds user_id keinem der Werte in der Liste blocked_user_ids entspricht:

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

In diesem Codebeispiel werden drei Ansichten mit den Namen user_events_blocked_removed, user_settings_blocked_removed und user_logs_blocked_removed erstellt, die keine der blockierten Nutzer-IDs enthalten.

Mit den globalen Dataform-Methoden und beliebigem JavaScript ES5-Code wie Schleifen und Konstanten können Sie mehrere Aktionen in einer JavaScript-Datei erstellen.

In Dataform können Sie die folgenden Aktionen mit JavaScript definieren:

Tables
Datenquellendeklarationen
Assertions
Benutzerdefinierte SQL-Vorgänge

Hinweise

Rufen Sie in der Google Cloud Console die Seite Dataform auf.

Zu Dataform
Wählen Sie ein Repository aus oder erstellen Sie ein Repository.
Wählen Sie einen Entwicklungsarbeitsbereich aus oder erstellen Sie einen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dataform Editor (roles/dataform.editor) für Arbeitsbereiche zu gewähren, damit Sie die Berechtigungen erhalten, die Sie zum Entwickeln eines SQL-Workflows mit JavaScript benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Möglicherweise können Sie die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

JavaScript-Datei in Dataform erstellen

Speichern Sie JavaScript-Dateien für Definitionen und Datenquellendeklarationen im Verzeichnis definitions/. So erstellen Sie eine neue JavaScript-Datei im Verzeichnis definitions/:

Klicken Sie im Bereich Dateien neben definitions/ auf das Dreipunkt-Menü .
Klicken Sie auf Datei erstellen.
Führen Sie im Bereich Neue Datei erstellen die folgenden Schritte aus:
1. Geben Sie im Feld Dateipfad hinzufügen nach definitions/ den Namen der Datei gefolgt von .js ein. Beispiel: definitions/definitions.js.
  
  Dateinamen dürfen nur Ziffern, Buchstaben, Bindestriche und Unterstriche enthalten.
2. Klicken Sie auf Datei erstellen.

Eigenschaften des Dataform-SQL-Workflows mit JavaScript festlegen

Sie können die folgenden globalen Dataform-Methoden verwenden, um SQL-Workflow-Objekte mit Dataform zu erstellen:

declare: Wird verwendet, um eine Datenquelle zu deklarieren.
publish: Wird zum Definieren einer Tabelle verwendet.
assert: Wird zum Erstellen einer Assertion verwendet.
operate: Wird zum Definieren eines benutzerdefinierten SQL-Vorgangs verwendet.

Jede der globalen Methoden enthält Attribute, mit denen Sie das erstellte Objekt konfigurieren können. Weitere Informationen zu globalen Methoden und ihren Eigenschaften finden Sie in der Referenz zu Dataform Core.

In der Methode publish(), mit der eine Tabelle erstellt wird, können Sie Tabellenattribute festlegen, indem Sie sie als zweites Methodenargument übergeben.

So übergeben Sie Tabellenattribute als zweites Argument von publish():

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option definitions/.
Wählen Sie eine JavaScript-Datei aus.

Fügen Sie in der Datei der Methode publish() Tabellenattribute im folgenden Format hinzu:

 method("first_method_argument", {
   property1: "property1_value",
   property2: "property2_value",
   property3: "property3_value",
 });

Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt, wie Sie Attribute für die Methode publish() festlegen, indem Sie die Attribute als zweites Argument der Methode übergeben:

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

Referenz-Includes in einer JavaScript-Datei

Sie können in einer JavaScript-Datei auf eine beliebige Include-Funktion, ein Makro oder eine Konstante verweisen. Weitere Informationen zu Einschluss in Dataform finden Sie unter Variablen und Funktionen mit JavaScript-Einschließen wiederverwenden.

Die Syntax für Verweise auf „Einschließen“-Elemente in einer JavaScript-Datei hängt vom Speicherort der Include-Datei ab. Dataform speichert solche Dateien im Verzeichnis „Einschließen“.

Verweis-URLs auf oberster Ebene

Wenn Sie auf eine Include-Datei der obersten Ebene verweisen möchten, müssen Sie beim Deklarieren der Variablen auf den Dateinamen verweisen.

Im folgenden Codebeispiel wird auf die Variablen serviceName und serviceId aus der Datei includes/service.js verwiesen:

  const {serviceName, serviceId} = service;

Verschachtelte Verweise

Wenn Sie auf eine verschachtelte eingebundene Datei verweisen möchten, geben Sie den Dateinamen in die JavaScript-Funktion „require“ ein.

Im folgenden Codebeispiel wird auf die Variablen serviceName und serviceId aus der Datei includes/allServices/service.js verwiesen:

  const {serviceName, serviceId} = require("includes/allServices/service.js");

Dataform-Abfragefunktionen in JavaScript-Methoden verwenden

Dataform bietet eine Reihe von integrierten Funktionen, die Sie innerhalb von Abfragen verwenden können, z. B. ref und self. Weitere Informationen zu den integrierten Funktionen von Dataform finden Sie in der Referenz zur Dataform API.

So verwenden Sie eine integrierte Abfragefunktion in einer JavaScript-Methode:

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option definitions/.
Wählen Sie eine JavaScript-Datei aus.
Geben Sie in der Datei eine globale Dataform-JavaScript-Methode ein.
Geben Sie in der Methode ein kontextfähiges ctx-Argument ein.
Optional: Wenn Sie JavaScript-Vorlagenstrings verwenden, setzen Sie das kontextfähige Argument in Graviszeichen ``.
Geben Sie im kontextfähigen Argument die Abfragefunktion mit ihrem Parameter als Kontextobjekt ein.
Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt die Abfragefunktion ref, die in ein kontextfähiges Argument der Methode „publish“ eingebunden ist:

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

SQL-Workflow-Datenquelle mit JavaScript deklarieren

Mit der Dataform declare-JavaScript-Methode können Sie mehrere Datenquellen in einer JavaScript-Deklarationsdatei deklarieren. Weitere Informationen zur Deklarationsmethode finden Sie in der Dataform Core-Referenz. Weitere Informationen zu Datenquellen in Dataform finden Sie unter Datenquelle deklarieren.

So deklarieren Sie eine Datenquelle in einer JavaScript-Datei:

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option „Definitionen/“.
Wählen Sie eine JavaScript-Datei aus.
Geben Sie in die Datei das folgende Code-Snippet ein:
```
 declare({
   database: "DATABASE_PROJECT_ID",
   schema: "BIGQUERY_SCHEMA",
   name: "RELATION_NAME",
 });
```
Ersetzen Sie Folgendes:
- DATABASE_PROJECT_ID: die Projekt-ID des Projekts, das die Datenquelle enthält
- BIGQUERY_SCHEMA: das BigQuery-Dataset, in dem die externe Beziehung besteht
- RELATION_NAME: der Name der Beziehung, mit der Sie später auf die Datenquelle in Dataform verweisen können
Wenn Sie eine weitere Datenquelle in derselben Datei deklarieren möchten, fügen Sie der Datei einen zusätzlichen declare-Block hinzu.
Optional: Klicken Sie auf Format.

Tabelle mit JavaScript definieren

Eine Tabelle kann mit der JavaScript-Methode publish von Dataform erstellt werden. Weitere Informationen zur Veröffentlichungsmethode finden Sie in der Referenz zu Dataform Core.

Sie können die folgenden Tabellentypen definieren: Tabelle, inkrementelle Tabelle und Ansicht. Weitere Informationen zum Definieren von Tabellen in Dataform finden Sie unter Tabelle erstellen.

So definieren Sie eine Tabelle in einer JavaScript-Datei:

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option definitions/.
Wählen Sie eine JavaScript-Datei aus.
Geben Sie in die Datei das folgende Code-Snippet ein:
```
 publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
```
1. Ersetzen Sie TABLE_NAME durch den Namen der Tabelle.
2. Ersetzen Sie SELECT_QUERY durch eine SQL-SELECT-Anweisung, die die Tabelle definiert.
Um den Tabellentyp festzulegen, Tabellenabhängigkeiten und eine Tabellenbeschreibung hinzuzufügen, legen Sie die Objektattribute der publish-Methode fest.
Um eine weitere Tabelle in derselben Datei zu definieren, wiederholen Sie Schritt 3 und Schritt 4.
Optional: Klicken Sie auf Format.

Manuelle Dataform-Assertions mit JavaScript definieren

Sie können manuelle SQL-Assertions in einer JavaScript-Datei mit der JavaScript-Methode „Dataform assert“ erstellen. Weitere Informationen zur Assert-Methode finden Sie in der Referenz zu Dataform Core.

Eine SQL-Abfrage mit manueller Assertion muss null Zeilen zurückgeben. Wenn die Abfrage beim Ausführen Zeilen zurückgibt, schlägt die Assertion fehl. Sie können mehrere Assertions in einer JavaScript-Datei erstellen.

Weitere Informationen zu Assertions in Dataform finden Sie unter Tabellen mit Assertions testen.

So erstellen Sie eine manuelle Assertion in einer JavaScript-Datei:

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option definitions/.
Wählen Sie eine JavaScript-Datei aus.
Geben Sie in die Datei das folgende Code-Snippet ein:
```
 assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");
```
1. Ersetzen Sie ASSERTION_NAME durch den Namen Ihrer benutzerdefinierten Assertion.
2. Ersetzen Sie CUSTOM_ASSERTION_QUERY durch Ihre SQL-Assertion-Abfrage.
Wiederholen Sie Schritt 3, um eine weitere Assertion in derselben Datei zu erstellen.
Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine JavaScript-Assertion, die bestätigt, dass kein Wert in source_table NULL ist:

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

Benutzerdefinierte SQL-Vorgänge mit JavaScript definieren

Mit der Dataform-Operations-JavaScript-Methode können Sie benutzerdefinierte SQL-Vorgänge in einer JavaScript-Datei definieren. Weitere Informationen zu benutzerdefinierten SQL-Vorgängen in Dataform finden Sie unter Benutzerdefinierte SQL-Vorgänge hinzufügen.

So definieren Sie einen benutzerdefinierten SQL-Vorgang mit JavaScript:

Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien die Option definitions/.
Wählen Sie eine JavaScript-Datei aus.
Geben Sie in die Datei das folgende Code-Snippet ein:
```
 operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
```
1. Ersetzen Sie OPERATION_NAME durch den Namen des benutzerdefinierten Vorgangs.
2. Ersetzen Sie CUSTOM_SQL_QUERY durch die benutzerdefinierte SQL-Abfrage.
Um einen weiteren benutzerdefinierten SQL-Vorgang in derselben Datei zu definieren, wiederholen Sie Schritt 3.
Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt einen benutzerdefinierten SQL-Vorgang in einer JavaScript-Datei, mit dem eine einzelne neue Zeile in some_table eingefügt und test_column der neuen Zeile auf 2 festgelegt wird:

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

Nächste Schritte

Weitere Informationen zu JavaScript-Methoden von Dataform und integrierten Abfragefunktionen finden Sie in der Referenz zu Dataform Core.
Weitere Informationen zum Entwickeln in Dataform mit JavaScript finden Sie unter Einführung in JavaScript in Dataform.