Tabellen mit Assertions testen

In diesem Dokument erfahren Sie, wie Sie mit Dataform Core Dataform-Tabellen-Assertions erstellen und Ihren Workflowcode testen.

Assertions

Eine Assertion ist eine Abfrage für einen Datenqualitätstest, mit der Zeilen gefunden werden, die gegen eine oder mehrere in der Abfrage angegebene Regeln verstoßen. Wenn die Abfrage Zeilen zurückgibt, schlägt die Assertion fehl. Dataform führt jedes Mal Assertions aus, wenn Ihr SQL-Workflow aktualisiert wird, und benachrichtigt Sie, wenn Assertions fehlschlagen.

Dataform erstellt automatisch Ansichten in BigQuery, die die Ergebnisse kompilierter Assertion-Abfragen enthalten. Wie in der Workfloweinstellungsdatei konfiguriert, erstellt Dataform diese Ansichten in einem Assertion-Schema, in dem Sie Assertion-Ergebnisse 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 Assertions für alle Dataform-Tabellentypen erstellen: Tabellen, inkrementelle Tabellen, Ansichten und materialisierte Ansichten.

Sie können Assertions auf folgende Arten erstellen:

• Integrierte Assertions zum Konfigurationsblock einer Tabelle hinzufügen

  Sie können dem Block config einer Tabelle integrierte Assertions hinzufügen und deren Bedingungen angeben.

• Manuelle Assertions in einer separaten SQLX-Datei hinzufügen

  Für erweiterte Anwendungsfälle oder für Datasets, die nicht von Dataform erstellt wurden, schreiben Sie manuell benutzerdefinierte Assertions in einer separaten SQLX-Datei.

Hinweise

1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

   Zur Seite „Dataform“

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

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

4. Definieren Sie eine Tabelle.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dataform Editor (roles/dataform.editor) für Arbeitsbereiche zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Assertions 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.

Integrierte Assertions erstellen

Sie können dem config-Block einer Tabelle integrierte Dataform-Assertions hinzufügen. Dataform führt diese Assertions nach der Tabellenerstellung aus. Nachdem Dataform die Tabelle veröffentlicht hat, können Sie die Assertion prüfen.

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

• nonNull

  Diese Bedingung bestätigt, dass die angegebenen Spalten in allen Tabellenzeilen nicht Null sind. Diese Bedingung wird für Spalten verwendet, die nie null sein dürfen.

  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 bestätigt, dass alle Tabellenzeilen der von Ihnen definierten Logik folgen. Jede Zeilenbedingung ist ein benutzerdefinierter SQL-Ausdruck und jede Tabellenzeile wird gegen jede Zeilenbedingung ausgewertet. Die Assertion schlägt fehl, wenn eine Tabellenzeile gegen eine Zeilenbedingung verstößt.

  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

  Diese Bedingung bestätigt, dass in einer bestimmten Spalte keine Tabellenzeilen den gleichen Wert haben.

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

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

• uniqueKeys

  Diese Bedingung bestätigt, dass in den angegebenen Spalten keine Tabellenzeilen den gleichen Wert haben. Die Assertion schlägt fehl, wenn die Tabelle mehr als eine Zeile mit denselben Werten für alle angegebenen Spalten enthält.

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

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

Assertions zum config-Block hinzufügen

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

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

Im folgenden Codebeispiel sehen Sie die Bedingungen, die im config-Block hinzugefügt wurden:

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 Assertions mit SQLX erstellen

Manuelle Assertions sind SQL-Abfragen, die Sie in eine dedizierte SQLX-Datei schreiben. Eine manuelle Assertion-SQL-Abfrage 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 Assertions in einer neuen SQLX-Datei hinzu:

1. Klicken Sie im Bereich Dateien neben definitions/ auf das Dreipunkt-Menü und dann auf 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 Ziffern, Buchstaben, Bindestriche und Unterstriche enthalten.

4. Klicken Sie auf Datei erstellen.

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

6. Geben Sie Folgendes in die Datei ein:

   config {
     type: "assertion"
   }
   

7. Schreiben Sie unter den Block config Ihre SQL-Abfrage oder mehrere Abfragen.

8. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine manuelle Assertion in einer SQLX-Datei, die bestätigt, 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

Assertions als Abhängigkeiten festlegen

Wenn Workflowaktion B von Workflowaktion A abhängt, die Assertions enthält, wird Dataform durch fehlgeschlagene Assertions von Aktion A nicht daran gehindert, Aktion B auszuführen. Um Aktion B nur auszuführen, wenn die Assertions von Aktion A bestanden wurden, müssen Sie die Assertions von Aktion A als Abhängigkeiten von Aktion B festlegen.

Sie können Assertions auf folgende Arten als Abhängigkeiten einer ausgewählten Aktion festlegen:

Ausgewählte Assertions als Abhängigkeiten festlegen

Sie können ausgewählte Assertions manuell als Abhängigkeiten festlegen, indem Sie sie dependencies: [ "" ] im config-Block der bearbeiteten Aktion hinzufügen.

Wenn Aktion B beispielsweise von Aktion A abhängt und Aktion B nur von ausgewählten Assertions der Aktion A abhängen soll, können Sie diese ausgewählten Assertions dem config-Aktionsblock B hinzufügen.

Sie können ausgewählte Assertions für alle Aktionstypen außer Datenquellendeklarationen manuell als Abhängigkeiten festlegen.

Assertions einer ausgewählten Abhängigkeitsaktion als Abhängigkeiten festlegen

Sie können den Parameter includeDependentAssertions so festlegen, dass alle direkten Assertions einer ausgewählten Abhängigkeits-Workflowaktion automatisch als Abhängigkeiten der bearbeiteten Aktion festgelegt werden. Dataform fügt diese Assertions bei jeder Kompilierung der Aktion als Abhängigkeiten hinzu, damit Abhängigkeiten auf dem neuesten Stand sind, wenn sich die Assertions der Abhängigkeitsaktion ändern.

Wenn Aktion C beispielsweise von den Aktionen A und B abhängt, aber nur Aktion C von den Assertions der Aktion A abhängen soll, können Sie die Aktion C bearbeiten und den Parameter includeDependentAssertions so festlegen, dass alle Assertions von Aktion A automatisch als Abhängigkeiten von Aktion C festgelegt werden.

Sie können den Parameter includeDependentAssertions für Aktionen der folgenden Typen festlegen:

• table
• view
• operations

Assertions für alle Abhängigkeitsaktionen als Abhängigkeiten festlegen

Sie können den Parameter dependOnDependencyAssertions so festlegen, dass automatisch alle direkten Assertions aus allen Abhängigkeitsaktionen der bearbeiteten Aktion als zusätzliche Abhängigkeiten der bearbeiteten Aktion festgelegt werden. Dataform fügt diese Assertions bei jeder Kompilierung der Aktion als Abhängigkeiten hinzu, damit Abhängigkeiten auf dem neuesten Stand sind, wenn sich die Assertions der Abhängigkeitsaktion ändern.

Wenn Aktion C beispielsweise von den Aktionen A und B abhängt, können Sie die Aktion C bearbeiten und den Parameter dependOnDependencyAssertions so festlegen, dass alle Assertions der Aktionen A und B automatisch als Abhängigkeiten der Aktion C festgelegt werden.

Sie können den Parameter dependOnDependencyAssertions für Aktionen der folgenden Typen festlegen:

• table
• view
• operations

Wenn Sie die Parameter dependOnDependencyAssertions und includeDependentAssertions in einer einzelnen Datei festlegen, hat der Parameter includeDependentAssertions Vorrang. Wenn Sie beispielsweise dependOnDependencyAssertions auf true und includeDependentAssertions für eine ausgewählte Abhängigkeitsaktion auf false setzen, fügt Dataform den Abhängigkeiten keine Assertions für diese Aktion hinzu.

Das folgende Codebeispiel zeigt die Parameter dependOnDependencyAssertions und includeDependentAssertions, die in derselben Tabellendefinitionsdatei festgelegt werden:

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

Im vorherigen Codebeispiel fügt Dataform während der Kompilierung alle direkten Assertions von actionA und actionC den Abhängigkeiten von tableName hinzu.

Ausgewählte Assertions als Abhängigkeiten festlegen

Wenn eine Workflowaktion nur ausgeführt werden soll, wenn die ausgewählten Assertions bestanden wurden, können Sie die ausgewählte Assertion zu dependencies: [ "" ] im config-Block der bearbeiteten Aktion hinzufügen.

So legen Sie eine ausgewählte Assertion als Abhängigkeit einer ausgewählten Workflowaktion fest:

1. Maximieren Sie im Entwicklungsarbeitsbereich im Bereich Dateien definitions/.
2. Wählen Sie eine SQLX-Datei für eine Workflowaktion aus.
3. Geben Sie im Block config der Aktionsdatei dependencies: [ "" ] ein.

4. Geben Sie in dependencies: [ "" ] den Namen der Aktions-Assertion oder den Dateinamen der manuellen Assertion, die Sie als Abhängigkeit festlegen möchten, in einem der folgenden Formate ein:

   nonNull

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • ACTION_DATASET_NAME: der Name des Datasets, in dem die Aktion definiert ist. Das Standard-Dataset wird in der Datei mit den Workfloweinstellungen definiert.
   • ACTION_NAME: der Name der Aktion, in der die Assertion definiert ist.

   rowConditions

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • DATASET_NAME: der Name des Datasets, in dem die Aktion definiert ist. Das Standard-Dataset wird in der Datei mit den Workfloweinstellungen definiert.
   • ACTION_NAME: der Name der Aktion, in der die Assertion definiert ist.

   uniqueKey

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • DATASET_NAME: der Name des Datasets, in dem die Tabelle definiert ist. Das Standard-Dataset wird in der Datei mit den Workfloweinstellungen definiert.
   • ACTION_NAME: der Name der Tabelle, in der die Assertion definiert ist.
   • INDEX: Index des Arrays von Schlüsseln, die in der Assertion uniqueKey definiert sind und als Abhängigkeit hinzugefügt werden sollen. Beispiel: 0 oder 1. Wenn in der Assertion nur ein Array von Schlüsseln definiert ist, ist der Index 0.

   uniqueKeys

   config {
     type: "ACTION_TYPE",
     dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • DATASET_NAME: der Name des Datasets, in dem die Tabelle definiert ist. Das Standard-Dataset wird in der Datei mit den Workfloweinstellungen definiert.
   • ACTION_NAME: der Name der Tabelle, in der die Assertion definiert ist.
   • INDEX: Index des Arrays von Schlüsseln, die in der Assertion uniqueKeys definiert sind und als Abhängigkeit hinzugefügt werden sollen, z. B. 0 oder 1. Wenn in der Assertion nur ein Array von Schlüsseln definiert ist, ist der Index 0.

   manuelle Assertion

   config {
     type: "ACTION_TYPE",
     dependencies: [ "MANUAL_ASSERTION_NAME"]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • MANUAL_ASSERTION_NAME ist der Name der manuellen Assertion.

5. Wiederholen Sie Schritt 4, um der bearbeiteten Tabelle eine weitere Assertion als Abhängigkeit hinzuzufügen.

6. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt Assertions, die zu Tabelle A hinzugefügt wurden und im Dataset dataform definiert sind:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

Das folgende Codebeispiel zeigt Assertions für Tabelle A, die als Abhängigkeiten zu Tabelle B hinzugefügt wurden:

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

Das folgende Codebeispiel zeigt eine manuelle Assertion, die in der Datei manualAssertion.sqlx definiert und einer Ansicht als Abhängigkeit hinzugefügt wurde:

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

Das folgende Codebeispiel zeigt die Datei manual_assertion und die Assertions der Tabelle sometable, die einer Tabelle als Abhängigkeiten hinzugefügt wurden:

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

Assertions einer ausgewählten Aktion als Abhängigkeiten festlegen

Soll eine Workflowaktion nur ausgeführt werden, wenn alle direkten Assertions einer ausgewählten Abhängigkeitsaktion bestanden wurden, setzen Sie den Parameter includeDependentAssertions in der bearbeiteten Aktion auf true. Dataform fügt während der Kompilierung automatisch direkte Assertions der ausgewählten Abhängigkeitsaktion zu Abhängigkeiten hinzu. Der Standardwert ist false.

So legen Sie alle Assertions einer ausgewählten Abhängigkeitsaktion als Abhängigkeiten fest:

1. Maximieren Sie im Entwicklungsarbeitsbereich im Bereich Dateien definitions/.
2. Wählen Sie eine SQLX-Datei für eine Workflowaktion aus.

3. Legen Sie in der Datei den Parameter includeDependentAssertions auf eine der folgenden Arten auf true fest:

   Im config-Block

   config {
   type: "ACTION_TYPE",
   dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
   }
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • DEPENDENCY_ACTION_NAME: der Name der Abhängigkeitsaktion, deren Assertions Sie als Abhängigkeiten der bearbeiteten Aktion festlegen möchten.

   In der SELECT-Anweisung

     config { type: "ACTION_TYPE" }
   
     SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}
   

   Ersetzen Sie Folgendes:

   • ACTION_TYPE: Typ der Workflowaktion: table, view oder operations.
   • DEPENDENCY_ACTION_NAME: der Name der Abhängigkeitsaktion, deren Assertions Sie als Abhängigkeiten der bearbeiteten Aktion festlegen möchten.

4. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt tableC, das von viewA, tableB und allen Assertions von tableB abhängig ist:

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

Im vorherigen Codebeispiel fügt Dataform während der Kompilierung automatisch alle direkten Assertions von tableB als Abhängigkeiten zu tableC hinzu.

Assertions aller Abhängigkeitsaktionen als Abhängigkeiten festlegen

Soll eine Workflowaktion nur ausgeführt werden, wenn alle direkten Assertions aller Abhängigkeitsaktionen bestanden wurden, setzen Sie den Parameter dependOnDependencyAssertions in der bearbeiteten Aktion auf true. Dataform fügt während der Kompilierung direkte Assertions von Abhängigkeitsaktionen automatisch als Abhängigkeiten hinzu. Der Standardwert ist false.

Wenn Sie den Parameter dependOnDependencyAssertions und die Parameter includeDependentAssertions in einer einzelnen Datei festlegen, hat der Parameter includeDependentAssertions bei der Abhängigkeitsaktion, für die er festgelegt ist, Priorität.

So legen Sie alle Assertions einer ausgewählten Abhängigkeitsaktion als Abhängigkeiten fest:

1. Maximieren Sie im Entwicklungsarbeitsbereich im Bereich Dateien definitions/.
2. Wählen Sie eine SQLX-Datei für eine Workflowaktion aus.

3. Legen Sie in der Datei den Parameter dependOnDependencyAssertions auf true im folgenden Format fest:

   config {
   type: "ACTION_TYPE",
   dependOnDependencyAssertions: true,
   dependencies: [ "dependency1", "dependency2" ]
   }
   

   Ersetzen Sie ACTION_TYPE: Typ der Workflowaktion. Unterstützte Werte sind table, view und operations.

4. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt sometableE, das von sometableA, sometabletableB, sometableC und sometableD sowie allen direkten Assertions von Abhängigkeitstabellen abhängt:

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

Im vorherigen Codebeispiel fügt Dataform während der Kompilierung automatisch alle direkten Assertions von sometableA, sometableB, sometableC und sometableD als Abhängigkeiten sometableE hinzu.

Nächste Schritte

• Weitere Informationen zu Assertion-Typen finden Sie unter Dataform API.
• Informationen zum Definieren von Assertions mit JavaScript finden Sie unter SQL-Workflows mit JavaScript erstellen.
• Informationen zum manuellen Ausführen von Workflows finden Sie unter Ausführung auslösen.