Testare tabelle con asserzioni

Questo documento illustra come utilizzare Dataform Core per creare Le asserzioni delle tabelle Dataform e testare il codice del flusso di lavoro.

Informazioni sulle asserzioni

Un'asserzione è una query di test della qualità dei dati che trova le righe che violano uno o più regole specificate nella query. Se la query restituisce delle righe, l'asserzione non riesce. Dataform esegue le asserzioni ogni volta che aggiorna il flusso di lavoro SQL e ti avvisa in caso di errori delle asserzioni.

Dataform crea automaticamente viste in BigQuery che contengono i risultati delle query di asserzione compilate. Come configurate nel file di impostazioni del flusso di lavoro, Dataform crea queste viste in uno schema di asserzioni in cui puoi esaminare i risultati delle asserzioni.

Ad esempio, per lo schema dataform_assertions predefinito, Dataform crea una vista in BigQuery nel seguente formato: dataform_assertions.assertion_name.

Puoi creare asserzioni per tutti i tipi di tabelle Dataform: tabelle, tabelle incrementali, viste e viste materializzate.

Puoi creare asserzioni nei seguenti modi:

Prima di iniziare

  1. Nella console Google Cloud, vai alla pagina Dataform.

    Vai alla pagina Dataform

  2. Seleziona o crea un repository.

  3. Seleziona o crea un'area di lavoro di sviluppo.

  4. Definisci una tabella.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare le asserzioni, chiedi all'amministratore di concederti Ruolo IAM dell'editor Dataform (roles/dataform.editor) nelle aree di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite la ruoli o altri ruoli predefiniti ruoli.

Crea asserzioni integrate

Puoi aggiungere asserzioni Dataform integrate al blocco config di un . Dataform esegue queste asserzioni dopo la creazione della tabella. Dopo il giorno Dataform pubblica la tabella; puoi esaminare l'asserzione.

Puoi creare le seguenti asserzioni nel blocco config di una tabella:

  • nonNull

    Questa condizione asserisce che le colonne specificate non sono nulle in tutte righe della tabella. Questa condizione viene utilizzata per le colonne che non possono mai essere null.

    Il seguente esempio di codice mostra un'asserzione nonNull nel blocco config di una tabella:

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

  • rowConditions

    Questa condizione asserisce che tutte le righe della tabella seguono la logica personalizzata che hai definire. Ogni condizione riga è un'espressione SQL personalizzata, mentre ogni riga della tabella valutate in base a ogni condizione di riga. L'asserzione ha esito negativo se una riga della tabella violi una qualsiasi condizione di riga.

    Il seguente esempio di codice mostra un'asserzione rowConditions personalizzata nel Blocco config di una tabella incrementale:

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

  • uniqueKey

    Questa condizione asserisce che, in una colonna specificata, nessuna riga della tabella ha il valore lo stesso valore.

    Il seguente esempio di codice mostra un'asserzione uniqueKey in config blocco di una vista:

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

  • uniqueKeys

    Questa condizione asserisce che, nelle colonne specificate, nessuna riga della tabella contiene lo stesso valore. L'asserzione ha esito negativo se è presente più di una riga nell' con gli stessi valori per tutte le colonne specificate.

    Il seguente esempio di codice mostra un'asserzione uniqueKeys in config blocco di una tabella:

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

Aggiungi asserzioni al blocco config

Per aggiungere asserzioni al blocco di configurazione di una tabella:

  1. Seleziona una tabella nel riquadro File dell'area di lavoro di sviluppo di definizione del file SQLX.
  2. Nel blocco config del file della tabella, inserisci assertions: {}.
  3. All'interno di assertions: {}, aggiungi le tue asserzioni.
  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra le condizioni aggiunte nel blocco config:

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

Creare asserzioni manuali con SQLX

Le asserzioni manuali sono query SQL che scrivi in un file SQLX dedicato. R la query SQL con asserzione manuale deve restituire zero righe. Se la query restituisce righe quando viene eseguita, l'asserzione non riesce.

Per aggiungere asserzioni manuali in un nuovo file SQLX, segui questi passaggi:

  1. Nel riquadro File, accanto a definitions/, fai clic sul menu Altro .
  2. Fai clic su Crea file.

  3. Nel campo Aggiungi un percorso file, inserisci il nome del file seguito da .sqlx. Ad esempio: definitions/custom_assertion.sqlx.

    I nomi file possono contenere solo numeri, lettere, trattini e trattini bassi.

  4. Fai clic su Crea file.

  5. Nel riquadro File, fai clic sul nuovo file.

  6. Nel file, inserisci:

    config {
  type: "assertion"
}

  7. Sotto il blocco config, scrivi la tua query SQL o più query.

  8. (Facoltativo) Fai clic su Formato.

L'esempio di codice seguente mostra un'asserzione manuale in un file SQLX che asserisce che i campi A, B e c non sono mai NULL in sometable:

config { type: "assertion" }

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

Imposta le asserzioni come dipendenze

Quando l'azione B del flusso di lavoro dipende dall'azione A del flusso di lavoro che ha asserzioni, fallimento delle asserzioni dell'azione A non blocca Dataform dall'esecuzione dell'azione B. Per eseguire l'azione B solo se le asserzioni dell'azione A superano, devi impostare le asserzioni dell'azione A come dipendenze dell'azione B.

Puoi impostare le asserzioni come dipendenze di un azione nei seguenti modi:

Imposta le asserzioni selezionate come dipendenze

Puoi impostare manualmente le asserzioni selezionate come dipendenze aggiungendole a dependencies: [ "" ] nel blocco config dell'azione modificata.

Ad esempio, se l'azione B dipende dall'azione A: e vuoi che l'azione B dipenda solo dalle asserzioni selezionate dell'azione A, puoi aggiungere le asserzioni selezionate al blocco config dell'azione B.

Puoi impostare manualmente le asserzioni selezionate come dipendenze per tutte le azioni tranne le dichiarazioni delle origini dati.

Imposta le asserzioni di un'azione di dipendenza selezionata come dipendenze

Puoi impostare il parametro includeDependentAssertions automaticamente imposta tutte le asserzioni dirette di un'azione del flusso di lavoro delle dipendenze selezionata come delle dipendenze dell'azione modificata. Dataform aggiunge queste asserzioni come durante ogni compilazione dell'azione per garantire che sono aggiornate se le dichiarazioni dell'azione di dipendenza cambiano.

Ad esempio, se l'azione C dipende dalle azioni A e B, ma vuoi che solo l'azione C dipenda dalle asserzioni dell'azione A, puoi modificare l'azione C e impostare il parametro includeDependentAssertions per impostare automaticamente tutte le asserzioni dell'azione A come dipendenze dell'azione C.

Puoi impostare il parametro includeDependentAssertions per le azioni dei seguenti tipi:

  • table
  • view
  • operations
Imposta le asserzioni di tutte le azioni di dipendenza come dipendenze

Puoi impostare dependOnDependencyAssertions per impostare automaticamente tutte le asserzioni dirette da tutte le azioni di dipendenza dell'azione modificata come dipendenze aggiuntive dell'azione modificata. Dataform aggiunge queste asserzioni come dipendenze durante ogni compilazione dell'azione per garantire che le dipendenze sono aggiornate se le dichiarazioni dell'azione di dipendenza cambiano.

Ad esempio, se l'azione C dipende dalle azioni A e B, puoi modificare l'azione C e impostare il parametro dependOnDependencyAssertions per impostare automaticamente tutte le asserzioni delle azioni A e B come dipendenze dell'azione C.

Puoi impostare il parametro dependOnDependencyAssertions per le azioni dei seguenti tipi:

  • table
  • view
  • operations

Quando imposti il parametro dependOnDependencyAssertions e includeDependentAssertions parametri in un singolo file, il parametro includeDependentAssertions ha la priorità. Ad esempio, se imposti dependOnDependencyAssertions su true, ma anche di impostare includeDependentAssertions su false per una dipendenza selezionata , Dataform non aggiungerà le asserzioni di questa azione alle dipendenze.

Il seguente esempio di codice mostra dependOnDependencyAssertions e includeDependentAssertions parametri impostati nello stesso file di definizione della tabella:

// filename is tableName.sqlx

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

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

Nell'esempio di codice precedente, Dataform aggiunge tutte le asserzioni dirette di actionA e actionC alle dipendenze di tableName durante la compilazione.

Imposta le asserzioni selezionate come dipendenze

Per eseguire un'azione del flusso di lavoro solo quando le asserzioni selezionate vengono superate, puoi aggiungere l'asserzione selezionata a dependencies: [ "" ] nel blocco config dell'azione modificata.

Per impostare un'asserzione selezionata come dipendenza da un'azione del flusso di lavoro selezionata, segui questi passaggi:

  1. Nell'area di lavoro di sviluppo, espandi definitions/ nel riquadro File.
  2. Seleziona un file SQLX di azione del flusso di lavoro.
  3. Nel blocco config del file delle azioni, inserisci dependencies: [ "" ].

  4. All'interno di dependencies: [ "" ], inserisci il nome dell'asserzione dell'azione oppure nome file dell'asserzione manuale che vuoi impostare come dipendenza in uno dei seguenti formati:

    nonNull

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • ACTION_DATASET_NAME: il nome del set di dati in cui è stata definita. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome dell'azione in cui è presente l'asserzione viene definito.

    rowConditions

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • DATASET_NAME: il nome del set di dati in cui è definita l'azione. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome dell'azione in cui è definita l'asserzione.

    uniqueKey

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • DATASET_NAME: il nome del set di dati in cui la tabella viene definito. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome della tabella in cui è presente l'asserzione viene definito.
    • INDEX: l'indice dell'array di chiavi definito nell' asserzione uniqueKey che vuoi aggiungere come dipendenza. Ad esempio: 0 o 1. Se nell'asserzione è definito un solo array di chiavi, l'indice è 0.

    uniqueKeys

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • DATASET_NAME: il nome del set di dati in cui la tabella viene definito. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome della tabella in cui è presente l'asserzione viene definito.
    • INDEX: l'indice dell'array di chiavi definito nell' asserzione uniqueKeys che vuoi aggiungere come dipendenza, ad esempio 0 o 1. Se nell'asserzione è definito un solo array di chiavi, l'indice è 0.

    asserzione manuale

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • MANUAL_ASSERTION_NAME il nome dell'asserzione manuale.

  5. Per aggiungere un'altra asserzione come dipendenza alla tabella modificata, ripeti il Passaggio 4.

  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra le asserzioni aggiunte alla tabella A: definita nel set di dati dataform:

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

Il seguente esempio di codice mostra le asserzioni della tabella A aggiunte come dipendenze alla tabella B:

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

Il seguente esempio di codice mostra un'asserzione manuale definita nel File manualAssertion.sqlx, aggiunto come dipendenza a una vista:

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

Il seguente esempio di codice mostra il file manual_assertion e asserzioni della tabella sometable aggiunte come dipendenze a una tabella:

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

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

Imposta le asserzioni di un'azione selezionata come dipendenze

Eseguire un'azione del flusso di lavoro solo quando tutte le asserzioni dirette di un'azione di dipendenza selezionata, Imposta il parametro includeDependentAssertions su true nell'azione modificata. Dataform aggiunge automaticamente asserzioni dirette della dipendenza selezionata un'azione sulle dipendenze durante la compilazione. Il valore predefinito è false.

Per impostare come dipendenze tutte le asserzioni di un'azione di dipendenza selezionata: segui questi passaggi:

  1. Nell'area di lavoro di sviluppo, espandi definitions/ nel riquadro File.
  2. Seleziona un file SQLX di azione del flusso di lavoro.

  3. Nel file, imposta il parametro includeDependentAssertions su true in uno dei seguenti modi:

    Nel blocco config

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • DEPENDENCY_ACTION_NAME: il nome dell'azione della dipendenza le asserzioni da impostare come dipendenze dell'azione modificata.

    Nell'istruzione SELECT

      config { type: "ACTION_TYPE" }

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

    Sostituisci quanto segue:

    • ACTION_TYPE: il tipo di azione del flusso di lavoro: table, view o operations.
    • DEPENDENCY_ACTION_NAME: il nome dell'azione della dipendenza le asserzioni da impostare come dipendenze dell'azione modificata.

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra tableC che dipende da viewA, tableB, e tutte le dichiarazioni di tableB:

// filename is tableC.sqlx

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

SELECT * FROM ...

Nell'esempio di codice precedente, Dataform aggiunge automaticamente tutti asserzioni dirette di tableB come dipendenze di tableC durante la compilazione.

Imposta le asserzioni di tutte le azioni di dipendenza come dipendenze

Eseguire un'azione del flusso di lavoro solo quando tutte le asserzioni dirette di tutte le azioni di dipendenza, Imposta il parametro dependOnDependencyAssertions su true nell'azione modificata. Dataform aggiunge automaticamente asserzioni dirette di dipendenza come dipendenze durante la compilazione. Il valore predefinito è false.

Quando imposti il parametro dependOnDependencyAssertions e includeDependentAssertions parametri in un singolo file, Il parametro includeDependentAssertions ha la priorità per la dipendenza per cui è stata impostata.

Per impostare come dipendenze tutte le asserzioni di un'azione di dipendenza selezionata: segui questi passaggi:

  1. Nell'area di lavoro di sviluppo, espandi definitions/ nel riquadro File.
  2. Seleziona un file SQLX di azione del flusso di lavoro.

  3. Nel file, imposta il parametro dependOnDependencyAssertions su true nel seguente formato:

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

    Sostituisci ACTION_TYPE: il tipo di azione del flusso di lavoro. I valori supportati includono table, view e operations.

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra sometableE che dipende da sometableA, sometabletableB, sometableC, e sometableD e tutte le asserzioni dirette di delle tabelle delle dipendenze:

// filename is sometableE.sqlx

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

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

Nell'esempio di codice precedente, Dataform aggiunge automaticamente tutti asserzioni dirette di sometableA, sometableB, sometableC e sometableD come dipendenze a sometableE durante la compilazione.

Passaggi successivi