Datenqualität testen

In diesem Dokument erfahren Sie, wie Sie Ihren Workflow-Code mit Dataform-Tabellenzusicherungen und Unittests testen.

Hinweis

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

    Zur Dataform-Seite

  2. Wählen Sie ein Repository aus oder erstellen Sie eines.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus oder erstellen Sie einen.

  4. Tabelle erstellen

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, damit Sie die nötigen Berechtigungen zum Erstellen von Zusicherungen und Unittests haben:

  • Dataform-Bearbeiter (roles/dataform.editor) für den Arbeitsbereich
  • So synchronisieren Sie Assertionsmetadaten mit Knowledge Catalog: Dataplex Catalog Editor (roles/dataplex.catalogEditor) für das Projekt oder die @bigquery-Eintragsgruppe

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

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

Testdaten mit Zusicherungen

Eine Assertion ist eine Datenqualitätstestabfrage, mit der Zeilen gefunden werden, die eine oder mehrere in der Abfrage angegebene Bedingungen verletzen. Wenn bei der Abfrage Zeilen zurückgegeben werden, schlägt die Assertion fehl. Dataform führt Assertionen jedes Mal aus, wenn der Workflow aktualisiert wird, und benachrichtigt Sie, wenn eine Assertion fehlschlägt.

Dataform erstellt automatisch Ansichten in BigQuery, die die Ergebnisse kompilierter Zusicherungsabfragen enthalten. Wie in der Datei mit den Workflow-Einstellungen konfiguriert, erstellt Dataform diese Ansichten in einem Assertionsschema, in dem Sie die Assertionsergebnisse prüfen können.

Für das Standardschema dataform_assertions erstellt Dataform beispielsweise eine Ansicht in BigQuery im folgenden Format: dataform_assertions.assertion_name.

Sie können Zusicherungen für alle Dataform-Tabellentypen erstellen: Tabellen, inkrementelle Tabellen, Ansichten und materialisierte Ansichten.

Sie können Zusicherungen auf folgende Weise erstellen:

Integrierte Behauptungen erstellen

Sie können dem config-Block einer Tabelle integrierte Dataform-Assertions hinzufügen. Dataform führt diese Zusicherungen nach dem Erstellen der Tabelle aus. Nachdem Dataform die Tabelle erstellt hat, können Sie auf dem Tab Workflow execution logs (Workflow-Ausführungsprotokolle) Ihres Arbeitsbereichs sehen, ob die Assertion bestanden wurde.

Sie können die folgenden Behauptungen im config-Block einer Tabelle erstellen:

  • nonNull

    Mit dieser Bedingung wird geprüft, ob die angegebenen Spalten in allen Tabellenzeilen nicht null sind. Diese Bedingung wird für Spalten verwendet, die niemals null sein können.

    Das folgende Codebeispiel zeigt eine nonNull-Assertion im config-Block einer Tabelle:

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...

  • rowConditions

    Mit dieser Bedingung wird sichergestellt, dass alle Tabellenzeilen der von Ihnen definierten benutzerdefinierten Logik entsprechen. Jede Zeilenbedingung ist ein benutzerdefinierter SQL-Ausdruck und jede Tabellenzeile wird anhand jeder Zeilenbedingung ausgewertet. Die Assertion schlägt fehl, wenn eine Tabellenzeile false ergibt.

    Das folgende Codebeispiel zeigt eine benutzerdefinierte rowConditions-Assertion im config-Block einer inkrementellen Tabelle:

config {
  type: "incremental",
  assertions: {
    rowConditions: [
      'signup_date is null or signup_date > "2022-08-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

  • uniqueKey

    Mit dieser Bedingung wird sichergestellt, dass in einer angegebenen Spalte keine Tabellenzeilen denselben Wert haben.

    Das folgende Codebeispiel zeigt eine uniqueKey-Assertion im config-Block einer Ansicht:

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...

  • uniqueKeys

    Diese Bedingung besagt, dass in den angegebenen Spalten keine Tabellenzeilen denselben Wert haben. Die Assertion schlägt fehl, wenn in der Tabelle mehr als eine Zeile mit denselben Werten für alle angegebenen Spalten vorhanden ist.

    Das folgende Codebeispiel zeigt eine uniqueKeys-Assertion im config-Block einer Tabelle:

config {
  type: "table",
  assertions: {
    uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
  }
}
SELECT ...

Dem Block „config“ Assertions hinzufügen

So fügen Sie dem Konfigurationsblock einer Tabelle Zusicherungen hinzu:

  1. Wählen Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien eine SQLX-Datei mit der Tabellendefinition aus.
  2. Geben Sie im config-Block der Tabellendatei assertions: {} ein.
  3. Fügen Sie in assertions: {} Ihre Behauptungen hinzu.
  4. Optional: Klicken Sie auf Formatieren.

Das folgende Codebeispiel zeigt die im Block config hinzugefügten Bedingungen:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
    rowConditions: [
      'signup_date is null or signup_date > "2019-01-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

Manuelle Zusicherungen mit SQLX erstellen

Manuelle Assertions sind SQL-Abfragen, die Sie in einer dedizierten SQLX-Datei schreiben. Eine SQL-Abfrage für eine manuelle Assertion muss null Zeilen zurückgeben. Wenn die Abfrage bei der Ausführung Zeilen zurückgibt, schlägt die Assertion fehl.

So fügen Sie manuelle Zusicherungen in eine neue SQLX-Datei ein:

  1. Klicken Sie im Bereich Dateien neben definitions/ auf das Menü  Mehr.
  2. Klicken Sie auf Datei erstellen.

  3. Geben Sie im Feld Dateipfad hinzufügen den Namen der Datei gefolgt von .sqlx ein. Beispiel: definitions/custom_assertion.sqlx

    Dateinamen dürfen nur Zahlen, Buchstaben, Bindestriche und Unterstriche enthalten.

  4. Klicken Sie auf Datei erstellen.

  5. Klicken Sie im Bereich Dateien auf die neue Datei.

  6. Geben Sie in der Datei Folgendes ein:

    config {
  type: "assertion"
}

  7. Schreiben Sie unterhalb des config-Blocks Ihre SQL-Abfrage oder mehrere Abfragen.

  8. Optional: Klicken Sie auf Formatieren.

Das folgende Codebeispiel zeigt eine manuelle Assertion in einer SQLX-Datei, die besagt, dass die Felder A, B und c in sometable nie NULL sind:

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("sometable")}
WHERE
  a IS NULL
  OR b IS NULL
  OR c IS NULL

Datenqualität mit Unittests testen

Einheitentests sind Datenqualitätstests, die in einer dedizierten .sqlx-Datei definiert werden. Dabei werden alle Abhängigkeiten der getesteten Workflowaktion simuliert und erwartete Ergebnisse bereitgestellt. Mit Unit-Tests können Sie Dataform-Aktionen anhand von kontrollierten Mock-Eingaben testen, um zu prüfen, ob der Aktionscode Grenzfälle, Nullwerte, Aggregationen, reguläre Ausdrücke und bedingte Logik korrekt verarbeitet.

Mocks für Aktionsabhängigkeiten, z. B. Vorgängertabellen, Ansichten oder Rohdeklarationen, auf die in der Funktion ${ref()} verwiesen wird, werden in input-Blöcken definiert. Jeder input-Block verweist anhand des Namens auf eine Abhängigkeit und enthält eine SQL-Abfrage, mit der die Mock-Zeilen definiert werden. Diese Abfrage besteht in der Regel aus einer Reihe von SELECT-Anweisungen in Kombination mit UNION ALL. Erwartete Ergebnisse sind SQL-Abfragen, die die Ergebnisse der Ausführung der angegebenen Eingaben für die SQL-Anweisung der Workflow-Aktion darstellen.

In Dataform werden Unittests zeilenweise ausgeführt. Das tatsächliche Ergebnis der Ausführung der SQL-Logik einer Workflowaktion für Mock-Daten wird mit einem erwarteten Ergebnissatz verglichen.

Unittests können die folgenden Status haben:

  • SUCCESS: Der Test wurde bestanden. Die tatsächlichen Ergebnisse entsprechen den erwarteten Ergebnissen.
  • FAILURE: Der Test ist fehlgeschlagen. Die tatsächlichen Ergebnisse stimmen nicht mit den erwarteten Ergebnissen überein.

Beschränkungen

Dataform-Einheitentests sind mit den folgenden Einschränkungen verfügbar:

  • Einheitentests sind ab Dataform Core-Version 3.0.56 verfügbar.
  • Die maximale Größe von Eingabedaten in einem Unittest beträgt 100 Zeilen pro Eingabe.

Einheitentests erstellen

Speichern Sie .sqlx-Dateien für Unittests im Verzeichnis definitions/. So erstellen Sie eine neue .sqlx-Datei für Unit-Tests im Verzeichnis definitions/:

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

    Zur Dataform-Seite

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Klicken Sie im Bereich Dateien neben definitions/ auf das Menü Mehr.

  5. Klicken Sie auf Datei erstellen.

  6. 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 _test.sqlx ein. Beispiel: definitions/customer_spend_test.sqlx.

      Dateinamen dürfen nur Zahlen, Buchstaben, Bindestriche und Unterstriche enthalten.

    2. Klicken Sie auf Datei erstellen.

  7. Fügen Sie in der Testdatei den folgenden config-Block hinzu:

    config {
  type: "test",
  dataset: "ACTION_NAME"
}

    Ersetzen Sie ACTION_NAME durch den Namen der Aktion, die in diesem Test validiert wird.

  8. Um die getestete Aktion zu simulieren, fügen Sie für jede Aktionsabhängigkeit einen input-Block hinzu und schreiben Sie eine SQL-Abfrage, mit der diese Abhängigkeit im folgenden Format getestet wird:

    input "DEPENDENCY_NAME" {
SELECT ...
SELECT ...
}

    Ersetzen Sie DEPENDENCY_NAME durch den Namen der getesteten Aktionsabhängigkeit, die durch diese Eingabe simuliert wird.

  9. Schreiben Sie unter die input-Blöcke Standard-SQL-Abfragen, die die erwarteten Ausgaberow in folgendem Format darstellen:

    -- Expected Output
SELECT ...
SELECT ...

Die erwarteten Ausgabedaten sollten nur die Zeilen und Spalten enthalten, die durch die getestete Aktion mit den Mock-Eingaben erzeugt werden sollen.

Das folgende Codebeispiel zeigt die Workflow-Aktion customer_spend.sqlx:

config {
type: "table",
name: "customer_spend"
}

SELECT
  c.customer_id,
  c.name,
  SUM(o.amount) AS total_completed_amount
FROM
  ${ref("source_customers")} c
  JOIN
  ${ref("source_orders")} o
  ON c.customer_id = o.customer_id
WHERE
  o.status = 'COMPLETED'
GROUP BY
  1, 2

Das folgende Codebeispiel zeigt den customer_spend_test.sqlx-Unittest, in dem Abhängigkeiten der customer_spend.sqlx-Aktion simuliert und erwartete Ergebnisse für die Mock-Objekte definiert werden:

config {
  type: "test",
  dataset: "customer_spend"
}

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, 'Bob' AS name UNION ALL
  SELECT 103 AS customer_id, 'Charlie' AS name
}

input "source_orders" {
  -- Alice has one completed and one pending order
  SELECT 1 AS order_id, 101 AS customer_id, 'COMPLETED' AS status, 100.0 AS amount UNION ALL
  SELECT 2 AS order_id, 101 AS customer_id, 'PENDING' AS status, 50.0 AS amount UNION ALL
  -- Bob has one completed order
  SELECT 3 AS order_id, 102 AS customer_id, 'COMPLETED' AS status, 250.0 AS amount UNION ALL
  -- Charlie has no orders
  SELECT 4 AS order_id, 999 AS customer_id, 'COMPLETED' AS status, 10.0 AS amount
}

-- Expected Output
SELECT 101 AS customer_id, 'Alice' AS name, 100.0 AS total_completed_amount UNION ALL
SELECT 102 AS customer_id, 'Bob' AS name, 250.0 AS total_completed_amount

Einheitentests ausführen

So führen Sie Einheitentests aus:

Console

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

    Zur Dataform-Seite

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Klicken Sie auf Ausführung starten  > Aktionen ausführen.

  5. Wählen Sie im Bereich Ausführen im Abschnitt Ausführungsmodus die Option Unittests aus.

  6. Wählen Sie eine der folgenden Optionen aus:

    • Unittests auswählen: Führt Unittests aus, die Sie manuell auswählen.
    • Getaggte Unittests auswählen: Führt Unittests mit einem ausgewählten Tag aus.
    • Alle Unittests: Führt alle Unittests im Arbeitsbereich aus.

  7. Optional: Wählen Sie in den Abschnitten Ausführungsoptionen das Kästchen Als interaktiven Job mit hoher Priorität ausführen aus, um Unit-Tests sofort auszuführen und die Ausführungsgeschwindigkeit zu priorisieren.

    Wenn Sie das Kästchen Als interaktiven Job mit hoher Priorität ausführen nicht auswählen, führt Dataform standardmäßig Komponententests mit Batchressourcen aus, wobei die Einsparung von Rechenkosten priorisiert wird.

  8. Klicken Sie auf Ausführung starten.

API

Wenn Sie Unittests programmatisch ausführen möchten, erstellen Sie einen Workflow-Aufruf mit der Methode WorkflowInvocations.create und legen Sie die folgenden Ausführungsparameter für Unittests im invocationConfig-Objekt fest:

"executionMode": "UNIT_TESTS_ONLY"
Dieser Parameter, der auf "UNIT_TESTS_ONLY" festgelegt ist, löst die Ausführung von Unittests aus, die im Repository definiert sind.
Optional: "queryPriority": "INTERACTIVE"
Wenn dieser Parameter auf "INTERACTIVE" gesetzt ist, werden Abfragen in Dataform sofort ausgeführt. Wenn nicht festgelegt, führt Dataform Unit-Tests mit der Standardpriorität für Batchabfragen aus.
Optional: "includedTargets": []
Mit diesem Parameter können Sie Einheitentests angeben, sodass Dataform nur diese Tests ausführt.
Optional: "includedTags": []
Mit diesem Parameter können Sie Tags angeben, damit Dataform nur die Unittests mit diesen Tags ausführt.

Das folgende Codebeispiel zeigt den Hauptteil eines Workflow-Aufrufs, mit dem alle im Repository my-repo definierten Unittests mit der Standardpriorität für Batchabfragen ausgeführt werden:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY"
  }
}

Das folgende Codebeispiel zeigt den Text eines Workflow-Aufrufs, bei dem nur der my-test-Unit-Test mit der Priorität für interaktive Abfragen ausgeführt wird:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTargets": [
      {
        "database": "my-project",
        "schema": "my-dataset",
        "name": "my-test"
      }
    ]
  }
}

Das folgende Codebeispiel zeigt den Hauptteil eines Workflow-Aufrufs, der Unit-Tests im Repository my-repo ausführt, die mit test-tag-1 oder test-tag-2 getaggt sind:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTags": [
      "test-tag-1",
      "test-tag-2"
    ]
  }
}

Unittest-Ergebnisse prüfen

Sie können die Unterschiede zwischen den erwarteten und den tatsächlichen Scripts eines Unit-Tests im kompilierten Diagramm oder unter Ausführungen ansehen.

Kompiliertes Diagramm

So rufen Sie die tatsächlichen und erwarteten Skripts eines Unittests im kompilierten Diagramm der Workflowaktionen auf:

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

    Zur Dataform-Seite

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Optional: Wenn Sie Unit-Tests sehen möchten, die mit den Aktionen verknüpft sind, die sie testen, anstatt sie als unabhängige Grafikknoten anzuzeigen, legen Sie die Einstellung includeTestsInCompiledGraph in der Datei workflow_settings.yaml auf true fest:

    1. Wählen Sie die Datei workflow_settings.yaml aus.
    2. Fügen Sie den folgenden Code hinzu:
    includeTestsInCompiledGraph: true

  5. Klicken Sie auf Kompiliertes Diagramm.

  6. Wählen Sie im kompilierten Diagramm einen Unit-Test aus und klicken Sie dann auf Abfrage.

  7. Vergleichen Sie das tatsächliche SQL-Script mit dem erwarteten SQL-Script.

Ausführungen

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

    Zur Dataform-Seite

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Klicken Sie auf Ausführungen und dann neben dem ausgewählten Unittest auf Details ansehen.

  5. Vergleichen Sie die Abfrage für tatsächliche Ergebnisse und die Abfrage für erwartete Ergebnisse.

Best Practices für Unit-Tests

Mock-Datasets klein halten
Halten Sie die Anzahl der Zeilen in den Mock-Eingabedaten unter 10, um die Kompilierung zu beschleunigen und das Debugging zu erleichtern.
Explizite Zeilenreihenfolge angeben
Fügen Sie sowohl Ihrer Aktionsabfrage als auch Ihrer Abfrage für die erwartete Ausgabe immer eine ORDER BY-Anweisung hinzu, um eine deterministische Zeilenreihenfolge bei der Auswertung zu gewährleisten.
Spalten in Ihren Mock-Anweisungen explizit umwandeln
Wenn Sie Spalten in Ihren Mock-Anweisungen explizit umwandeln, z. B. mit CAST(100 AS INT64), wird die Typstrenge beibehalten und Kompilierungsfehler werden vermieden.
Testläufe mit NULL- oder fehlenden Werten einbeziehen
Wenn Sie Testläufe mit NULL- oder fehlenden Werten in Ihre Mock-Eingabeabfragen einbeziehen, wird sichergestellt, dass Ihre COALESCE-Anweisungen, String-Operationen und Filterkriterien unvollständige oder Null-Produktionsdaten sicher verarbeiten.

Das folgende Codebeispiel zeigt einen NULL-Testlauf:

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, NULL AS name -- Test null handling
}

Nächste Schritte