Imposta le dipendenze

Questo documento mostra come definire la relazione tra gli oggetti nel flusso di lavoro in Dataform dichiarando le dipendenze.

Puoi definire una relazione di dipendenza tra gli oggetti di un workflow. In una relazione di dipendenza, l'esecuzione dell'oggetto dipendente dipende dall'esecuzione dell'oggetto di dipendenza. Ciò significa che Dataform esegue la dipendenza dopo la dipendenza. Definisci la relazione dichiarando le dipendenze all'interno del file di definizione SQLX dell'oggetto dipendente.

Le dichiarazioni di dipendenza costituiscono un albero delle dipendenze del workflow che determina l'ordine in cui Dataform esegue le azioni del workflow.

Puoi definire la relazione di dipendenza tra le seguenti azioni del flusso di lavoro:

Dichiarazioni dell'origine dati
Dichiarazioni delle origini dati BigQuery che consentono di fare riferimento a queste origini dati nelle definizioni delle tabelle Dataform e nelle operazioni SQL. Puoi impostare una dichiarazione di origine dati come dipendenza, ma non come dipendente.
Tabelle
Tabelle create in Dataform in base alle origini dati dichiarate o ad altre tabelle nel flusso di lavoro. Dataform supporta i seguenti tipi di tabelle: tabella, tabella incrementale, visualizzazione e vista materializzata. Puoi impostare una tabella come dipendenza e come dipendente.
Operazioni SQL personalizzate
Istruzioni SQL che Dataform esegue in BigQuery così come sono, senza modifiche. Puoi impostare un'operazione SQL personalizzata definita in un file type: operations come dipendenza e come dipendente. Per dichiarare un'operazione SQL personalizzata come dipendenza nella funzione ref, devi impostare la proprietà hasOutput su true nel file di definizione SQLX dell'operazione SQL personalizzata.
Assertions
Query di test della qualità dei dati che puoi utilizzare per testare i dati delle tabelle. Dataform esegue le asserzioni ogni volta che aggiorna il flusso di lavoro e ti avvisa se una qualsiasi asserzione non riesce. Puoi impostare un'asserzione definita in un file type: assertion come dipendenza e come dipendente dichiarando le dipendenze nel blocco config.

Puoi definire la relazione di dipendenza nei seguenti modi:

Prima di iniziare

  1. Crea e inizializza un workspace di sviluppo nel repository.
  2. (Facoltativo) Dichiara un'origine dati.
  3. Crea almeno due azioni del flusso di lavoro: tabelle, asserzioni, dichiarazioni di origini dati o operazioni.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per dichiarare le dipendenze per tabelle, asserzioni, dichiarazioni di origini dati e operazioni SQL personalizzate, chiedi all'amministratore di concederti il ruolo IAM Editor Dataform (roles/dataform.editor) negli spazi di lavoro. 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.

Dichiarare una dipendenza come argomento della funzione ref

Per fare riferimento e dichiarare automaticamente una dipendenza in un'istruzione SELECT, aggiungi la dipendenza come argomento della funzione ref.

La funzione ref è una funzione integrata di Dataform Core che ti consente di fare riferimento e dipendere automaticamente da qualsiasi tabella, dichiarazione dell'origine dati o operazione SQL personalizzata con la proprietà hasOutput impostata su true nel workflow.

Per saperne di più sulla funzione ref, consulta la documentazione di riferimento sui metodi di contesto principali di Dataform.

Per saperne di più sull'utilizzo della funzione ref in una definizione di tabella, vedi Informazioni sulle definizioni di tabella.

Il seguente esempio di codice mostra la dichiarazione dell'origine dati source_data aggiunta come argomento della funzione ref nel file di definizione SQLX di una tabella incrementale:incremental_table.sqlx

// filename is incremental_table.sqlx

config { type: "incremental" }

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

Nell'esempio di codice precedente, source_data viene dichiarato automaticamente come dipendenza di incremental_table.

Il seguente esempio di codice mostra il file SQLX di definizione della tabella some_table aggiunto come argomento della funzione ref nel file di definizione SQLX di un'asserzione:custom_assertion.sqlx

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

Nell'esempio di codice precedente, some_table viene dichiarato automaticamente come dipendenza di custom_assertion. Durante l'esecuzione, Dataform esegue some_table prima e poi custom_assertion una volta creato some_table.

Dichiarare le dipendenze nel blocco config

Per dichiarare le dipendenze a cui non viene fatto riferimento nella definizione dell'istruzione SQL della dipendenza, ma che devono essere eseguite prima della tabella, dell'asserzione o dell'operazione SQL personalizzata, segui questi passaggi:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi la directory definitions/.
  2. Seleziona il file SQLX della tabella, dell'asserzione o dell'operazione SQL personalizzata che vuoi modificare.

  3. Nel blocco config del file, inserisci il seguente snippet di codice:

    dependencies: [ "DEPENDENCY", ]

    Sostituisci DEPENDENCY con la stringa di destinazione, ad esempio il nome file dell'azione che vuoi aggiungere come dipendenza. Puoi inserire più target separati da virgole.

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra la tabella some_table e l'asserzione some_assertion aggiunte come dipendenze al blocco config di un file di definizione della tabella:

config { dependencies: [ "some_table", "some_assertion" ] }

Impostare le asserzioni come dipendenze

Quando l'azione del flusso di lavoro B dipende dall'azione del flusso di lavoro A, che ha asserzioni, il mancato rispetto delle asserzioni dell'azione A non impedisce a Dataform di eseguire l'azione B. Per eseguire l'azione B solo se le asserzioni dell'azione A vengono superate, devi impostare le asserzioni dell'azione A come dipendenze dell'azione B.

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

Imposta le asserzioni selezionate come dipendenze

Puoi impostare manualmente le asserzioni selezionate come dipendenze aggiungendole alla riga 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 queste asserzioni selezionate al blocco config dell'azione B.

Puoi impostare manualmente le asserzioni selezionate come dipendenze per tutti i tipi di azione, ad eccezione delle dichiarazioni delle origini dati.

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

Puoi impostare il parametro includeDependentAssertions in modo da impostare automaticamente tutte le asserzioni dirette di un'azione del flusso di lavoro di dipendenza selezionata come dipendenze dell'azione modificata. Dataform aggiunge queste asserzioni come dipendenze durante ogni compilazione dell'azione per verificare che le dipendenze siano aggiornate se le asserzioni dell'azione di dipendenza cambiano.

Ad esempio, se l'azione C dipende dalle azioni A e B, ma vuoi che l'azione C dipenda solo dalle asserzioni dell'azione A, puoi modificare l'azione C e impostare il parametro includeDependentAssertions in modo che tutte le asserzioni dell'azione A vengano impostate automaticamente 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 il parametro dependOnDependencyAssertions per impostare automaticamente tutte le asserzioni dirette di 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 verificare che le dipendenze siano aggiornate se le asserzioni 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 in modo da 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 i parametri includeDependentAssertions in un unico file, il parametro includeDependentAssertions ha la priorità. Ad esempio, se imposti dependOnDependencyAssertions su true, ma imposti anche includeDependentAssertions su false per un'azione di dipendenza selezionata, Dataform non aggiungerà le asserzioni di questa azione alle dipendenze.

Il seguente esempio di codice mostra i parametri dependOnDependencyAssertions e includeDependentAssertions 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 alla riga dependencies: [ "" ] nel blocco config dell'azione modificata.

Per impostare un'asserzione selezionata come dipendenza di un'azione del flusso di lavoro selezionata:

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

  4. All'interno di dependencies: [ "" ], inserisci il nome dell'asserzione di azione o il 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 è 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.

    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 è definita la tabella. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome della tabella in cui è definita l'asserzione.
    • 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 è definita la tabella. Il set di dati predefinito è definito nel file delle impostazioni del flusso di lavoro.
    • ACTION_NAME: il nome della tabella in cui è definita l'asserzione.
    • 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 e aggiunta come dipendenza a una visualizzazione:

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

Il seguente esempio di codice mostra il file manual_assertion e le 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

Per eseguire un'azione del flusso di lavoro solo quando tutte le asserzioni dirette di un'azione di dipendenza selezionata vengono superate, imposta il parametro includeDependentAssertions su true nell'azione modificata. Dataform aggiunge automaticamente le asserzioni dirette dell'azione di dipendenza selezionata alle dipendenze durante la compilazione. Il valore predefinito è false.

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

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

  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 di dipendenza con le asserzioni che vuoi impostare come dipendenze dell'azione modificata.

    Nella dichiarazione 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 di dipendenza con le asserzioni che vuoi 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 da tutte le asserzioni 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 tutte le asserzioni dirette di tableB come dipendenze di tableC durante la compilazione.

Imposta le asserzioni di tutte le azioni di dipendenza come dipendenze

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

Quando imposti il parametro dependOnDependencyAssertions e i parametri includeDependentAssertions in un unico file, il parametro includeDependentAssertions ha la priorità per l'azione di dipendenza per cui è impostato.

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

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

  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, sometableD e da tutte le asserzioni dirette 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 tutte le asserzioni dirette di sometableA, sometableB, sometableC e sometableD come dipendenze di sometableE durante la compilazione.

Fare riferimento a una tabella con un nome tabella sottoposto a override

  • Per fare riferimento a una tabella con un nome di tabella sottoposto a override, nella funzione ref, inserisci il nome della tabella sottoposto a override impostato in name: "".

Il seguente esempio di codice fa riferimento a una tabella con un nome sostituito da overridden_name:

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

Per ulteriori informazioni sull'override dei nomi delle tabelle, vedi Override delle impostazioni della tabella.

Passaggi successivi