Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Testare la qualità dei dati

Questo documento mostra come testare il codice del flusso di lavoro con asserzioni di tabelle e test delle unità Dataform.

Prima di iniziare

Nella console Google Cloud , vai alla pagina Dataform.

Vai alla pagina Dataform
Seleziona o crea un repository.
Seleziona o crea un workspace di sviluppo.
Crea una tabella.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare asserzioni e unit test, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Editor Dataform (roles/dataform.editor) sul workspace
Per sincronizzare i metadati delle asserzioni con Knowledge Catalog: Editor di Dataplex Catalog (roles/dataplex.catalogEditor) sul progetto o sul gruppo di voci @bigquery

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

Testare i dati con le asserzioni

Un'asserzione è una query di test della qualità dei dati che trova le righe che violano una o più condizioni specificate nella query. Se la query restituisce delle righe, l'asserzione non riesce. Dataform esegue asserzioni ogni volta che aggiorna il workflow e ti avvisa se una qualsiasi asserzione non va a buon fine.

Dataform crea automaticamente in BigQuery viste che contengono i risultati delle query di asserzione compilate. Come configurato nel file delle impostazioni del flusso di lavoro, Dataform crea queste viste in uno schema di asserzioni in cui puoi controllare 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:

Aggiungi asserzioni integrate al blocco di configurazione di una tabella.

Puoi aggiungere asserzioni integrate al blocco config di una tabella e specificarne le condizioni.
Aggiungi asserzioni manuali in un file SQLX separato.

Scrivi manualmente asserzioni personalizzate in un file SQLX separato per casi d'uso avanzati o per set di dati non creati da Dataform.

Nota: le asserzioni Dataform vengono integrate automaticamente con la scheda di valutazione della qualità dei dati di Knowledge Catalog (anteprima). Durante l'esecuzione della pipeline, i risultati di qualsiasi asserzione Dataform vengono pubblicati automaticamente in Knowledge Catalog. Questi risultati vengono inseriti nella scheda di valutazione della qualità dei dati di Knowledge Catalog con uno stato di superamento o errore. Ogni esecuzione sovrascrive i prospetti della qualità dei dati esistenti pubblicati dalle esecuzioni precedenti di Dataform, ma non influisce sui prospetti creati dalle scansioni dei dati di Knowledge Catalog. Per controllare lo stato di un aggiornamento dei metadati, segui le istruzioni in Esaminare i log di esecuzione dello spazio di lavoro. Per visualizzare questi risultati in Knowledge Catalog, segui le istruzioni riportate nella sezione Cercare risorse.

Creare asserzioni integrate

Puoi aggiungere asserzioni Dataform integrate al blocco config di una tabella. Dataform esegue queste asserzioni dopo la creazione della tabella. Dopo che Dataform crea la tabella, puoi verificare se l'asserzione è stata superata nella scheda Log di esecuzione del flusso di lavoro del tuo spazio di lavoro.

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

nonNull

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

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 afferma che tutte le righe della tabella seguono la logica personalizzata che definisci. Ogni condizione di riga è un'espressione SQL personalizzata e ogni riga della tabella viene valutata in base a ogni condizione di riga. L'asserzione non riesce se una riga della tabella restituisce false.

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 afferma che, in una colonna specificata, nessuna riga della tabella ha lo stesso valore.

Il seguente esempio di codice mostra un'asserzione uniqueKey nel blocco config di una visualizzazione:

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

uniqueKeys

Questa condizione afferma che, nelle colonne specificate, nessuna riga della tabella ha lo stesso valore. L'asserzione non riesce se nella tabella è presente più di una riga con gli stessi valori per tutte le colonne specificate.

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

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

Aggiungere asserzioni al blocco `config`

Per aggiungere asserzioni al blocco di configurazione di una tabella:

Nell'area di lavoro di sviluppo, nel riquadro File, seleziona un file SQLX di definizione della tabella.
Nel blocco config del file della tabella, inserisci assertions: {}.
All'interno di assertions: {}, aggiungi le tue asserzioni.
(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 ...

Crea asserzioni manuali con SQLX

Le asserzioni manuali sono query SQL che scrivi in un file SQLX dedicato. Una query SQL di 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:

Nel riquadro File, accanto a definitions/, fai clic sul menu Altro.
Fai clic su Crea file.
Nel campo Aggiungi un percorso del file, inserisci il nome del file seguito da .sqlx. Ad esempio: definitions/custom_assertion.sqlx.

I nomi dei file possono includere solo numeri, lettere, trattini e trattini bassi.
Fai clic su Crea file.
Nel riquadro File, fai clic sul nuovo file.
Nel file, inserisci:
```
config {
  type: "assertion"
}
```
Sotto il blocco config, scrivi la query SQL o più query.
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un'asserzione manuale in un file SQLX che afferma 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

Testare la qualità dei dati con i test delle unità

Un test unitario è un test di qualità dei dati, definito in un file .sqlx dedicato, che simula tutte le dipendenze dell'azione del flusso di lavoro testata e fornisce i risultati previsti. Puoi utilizzare i test unitari per testare le azioni Dataform rispetto a input simulati controllati per verificare se il codice dell'azione gestisce correttamente i casi limite, i valori null, le aggregazioni, le espressioni regolari e la logica condizionale.

I mock per le dipendenze delle azioni, come tabelle, viste o dichiarazioni non elaborate precedenti a cui viene fatto riferimento nella funzione ${ref()}, sono definiti nei blocchi input. Ogni blocco input fa riferimento a una dipendenza in base al nome e contiene una query SQL che definisce le righe simulate. Questa query è in genere una serie di istruzioni SELECT combinate con UNION ALL. I risultati previsti sono query SQL che rappresentano i risultati dell'esecuzione degli input specificati nell'istruzione SQL dell'azione del flusso di lavoro.

Dataform esegue test unitari riga per riga e confronta il risultato effettivo dell'esecuzione della logica SQL di un'azione del workflow rispetto ai dati simulati con un insieme di risultati previsto.

I test delle unità vengono risolti nei seguenti stati:

SUCCESS: Il test è stato superato. I risultati effettivi corrispondono a quelli previsti.
FAILURE: il test non è riuscito. I risultati effettivi non corrispondono a quelli previsti.

Limitazioni

I test delle unità Dataform sono disponibili con le seguenti limitazioni:

I test delle unità sono disponibili con Dataform Core versione 3.0.56 e successive.
La dimensione massima dei dati di input in un test unitario è di 100 righe per input.

Crea test delle unità

Archivia i file .sqlx per i test delle unità nella directory definitions/. Per creare un nuovo file .sqlx di test delle unità nella directory definitions/, segui questi passaggi:

Nella console Google Cloud , vai alla pagina Dataform.

Vai alla pagina Dataform
Seleziona un repository.
Seleziona un workspace di sviluppo.
Nel riquadro File, accanto a definitions/, fai clic sul menu Altro.
Fai clic su Crea file.
Nel riquadro Crea nuovo file:
1. Nel campo Aggiungi un percorso del file, dopo definitions/, inserisci il nome del file seguito da _test.sqlx. Ad esempio definitions/customer_spend_test.sqlx.
  
  I nomi dei file possono includere solo numeri, lettere, trattini e trattini bassi.
2. Fai clic su Crea file.
Nel file di test, aggiungi il seguente blocco config:
```
config {
  type: "test",
  dataset: "ACTION_NAME"
}
```
Sostituisci ACTION_NAME con il nome dell'azione che questo test convalida.
Per simulare l'azione testata, aggiungi un blocco input per ogni dipendenza dell'azione e scrivi una query SQL che testa la dipendenza nel seguente formato:
```
input "DEPENDENCY_NAME" {
SELECT ...
SELECT ...
}
```
Sostituisci DEPENDENCY_NAME con il nome della dipendenza dell'azione testata che questo input simula.
Sotto i blocchi input, scrivi query SQL standard che rappresentano le righe di output previste nel seguente formato:
```
-- Expected Output
SELECT ...
SELECT ...
```

Le query di output previste devono restituire solo le righe e le colonne che l'azione testata deve produrre in base agli input simulati.

Il seguente esempio di codice mostra l'azione del flusso di lavoro 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

Il seguente esempio di codice mostra il test delle unità customer_spend_test.sqlx che simula le dipendenze dell'azione customer_spend.sqlx e definisce i risultati previsti per le simulazioni:

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

Test delle unità

Per eseguire i test unitari:

Console

Nella console Google Cloud , vai alla pagina Dataform.

Vai alla pagina Dataform
Seleziona un repository.
Seleziona un workspace di sviluppo.
Fai clic su Avvia esecuzione > Esegui azioni.
Nel riquadro Esegui, nella sezione Modalità di esecuzione, seleziona Test unitari.
Seleziona una delle seguenti opzioni:
- Seleziona test delle unità: esegue i test delle unità selezionati manualmente.
- Seleziona test delle unità taggati: esegue i test delle unità con un tag selezionato.
- Tutti i test delle unità: esegue tutti i test delle unità nello spazio di lavoro.
(Facoltativo) Nelle sezioni Opzioni di esecuzione, seleziona la casella di controllo Esegui come job interattivo con priorità alta per eseguire immediatamente i test unitari, dando la priorità alla velocità di esecuzione.

Se non selezioni la casella di controllo Esegui come job interattivo con priorità alta, Dataform esegue i test unitari utilizzando le risorse batch per impostazione predefinita, dando la priorità al risparmio sui costi di calcolo.
Fai clic su Avvia esecuzione.

API

Per eseguire i test delle unità in modo programmatico, crea una chiamata del flusso di lavoro utilizzando il metodo WorkflowInvocations.create e imposta i seguenti parametri di esecuzione dei test delle unità nell'oggetto invocationConfig:

"executionMode": "UNIT_TESTS_ONLY": Questo parametro, impostato su "UNIT_TESTS_ONLY", attiva l'esecuzione dei test unitari definiti nel repository.
Facoltativo: "queryPriority": "INTERACTIVE": Quando questo parametro è impostato su "INTERACTIVE", Dataform esegue immediatamente le query. Se non è impostata, Dataform esegue i test delle unità con la priorità di query batch predefinita.
Facoltativo: "includedTargets": []: Questo parametro ti consente di specificare i test unitari in modo che Dataform esegua solo questi test.
Facoltativo: "includedTags": []: Questo parametro ti consente di specificare i tag in modo che Dataform esegua solo i test delle unità contrassegnati con questi tag.

Il seguente esempio di codice mostra il corpo di una chiamata del flusso di lavoro che esegue tutti i test unitari definiti nel repository my-repo con la priorità di query batch predefinita:

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

Il seguente esempio di codice mostra il corpo di una chiamata del flusso di lavoro che esegue solo il test delle unità my-test con la priorità di query interattiva:

{
  "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"
      }
    ]
  }
}

Il seguente esempio di codice mostra il corpo di una chiamata del flusso di lavoro che esegue i test delle unità nel repository my-repo contrassegnati con test-tag-1 o test-tag-2:

{
  "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"
    ]
  }
}

Esaminare i risultati dei test delle unità

Puoi esaminare le differenze tra gli script previsti e quelli effettivi di un test unitario nel grafico compilato o in Esecuzioni.

Grafico compilato

Per visualizzare gli script effettivi e previsti di un test unitario nel grafico compilato delle azioni del flusso di lavoro, segui questi passaggi:

Nella console Google Cloud , vai alla pagina Dataform.

Vai alla pagina Dataform
Seleziona un repository.
Seleziona un workspace di sviluppo.
(Facoltativo) Per visualizzare i test unitari collegati alle azioni che testano, anziché visualizzarli come nodi del grafico indipendenti, imposta l'impostazione includeTestsInCompiledGraph su true nel file workflow_settings.yaml:
1. Seleziona il file workflow_settings.yaml.
2. Aggiungi il codice seguente:
```
includeTestsInCompiledGraph: true
```
Fai clic su Grafico compilato.
Nel grafico compilato, seleziona un test delle unità e poi fai clic su Query.
Confronta lo script SQL effettivo e lo script SQL previsto.

Esecuzioni

Nella console Google Cloud , vai alla pagina Dataform.

Vai alla pagina Dataform
Seleziona un repository.
Seleziona un workspace di sviluppo.
Fai clic su Esecuzioni, quindi su Visualizza dettagli accanto al test unitario selezionato.
Confronta la query sui risultati effettivi e la query sui risultati previsti.

Best practice per i test unitari

Mantieni piccoli i set di dati simulati: Mantieni i dati di input simulati sotto le 10 righe per una compilazione più rapida e un debug più semplice.
Specifica un ordine esplicito delle righe: Aggiungi sempre una clausola ORDER BY sia alla query di azione sia alla query di output prevista per garantire un ordinamento deterministico delle righe durante la valutazione.
Esegui il cast esplicito delle colonne nelle istruzioni simulate: Il casting esplicito delle colonne nelle istruzioni simulate, ad esempio utilizzando CAST(100 AS INT64), mantiene la rigidità del tipo ed evita errori di compilazione.
Includi scenari di test con NULL o valori mancanti: L'inclusione di scenari di test con NULL o valori mancanti nelle query di simulazione di input garantisce che le istruzioni COALESCE, le operazioni sulle stringhe e i criteri di filtro gestiscano in modo sicuro i dati di produzione incompleti o nulli.

Il seguente esempio di codice mostra un caso di test NULL:

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

Passaggi successivi

Per scoprire di più sui tipi di asserzione, consulta l'API Dataform.
Per scoprire come definire le asserzioni con JavaScript, consulta Creare flussi di lavoro esclusivamente con JavaScript.
Per scoprire come eseguire manualmente i flussi di lavoro, consulta Attivare manualmente le esecuzioni.

Testare la qualità dei dati Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.