Configurare una tabella incrementale

Questo documento mostra come utilizzare Dataform core per configurare una tabella incrementale.

Informazioni su una tabella incrementale

Dataform aggiorna le tabelle in modo diverso in base al tipo di tabella. Durante ogni esecuzione di una tabella o di una vista, Dataform ricostruisce l'intera tabella o vista da zero.

Quando definisci una tabella incrementale, Dataform la crea da zero solo la prima volta. Durante le esecuzioni successive, Dataform inserisce o unisce nuove righe nella tabella incrementale solo in base alle condizioni che configuri.

Dataform inserisce nuove righe solo nelle colonne già esistenti nella tabella incrementale. Se apporti modifiche alla query di definizione della tabella incrementale, ad esempio aggiungi una nuova colonna, devi ricostruire la tabella da zero. Per farlo, la volta successiva che attivi un'esecuzione della tabella, seleziona l'opzione Esegui con aggiornamento completo.

Ecco alcuni casi d'uso comuni per le tabelle incrementali:

Ottimizzazione delle prestazioni
Per alcuni tipi di dati, come i log web o i dati di analisi, potresti voler elaborare solo i nuovi record anziché rielaborare l'intera tabella.
Riduzione della latenza
Puoi utilizzare le tabelle incrementali per eseguire i flussi di lavoro rapidamente, ma di frequente, riducendo la latenza a valle delle tabelle di output.
Istantanee giornaliere
Puoi configurare una tabella incrementale per creare istantanee giornaliere dei dati della tabella, ad esempio per l'analisi longitudinale delle impostazioni utente memorizzate in un database di produzione.

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. Crea una tabella del tipo incremental.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare una tabella incrementale, chiedi all'amministratore di concederti il ruolo IAM Editor di Dataform (roles/dataform.editor) negli spazi di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Elaborare un sottoinsieme di righe in una tabella incrementale

Per determinare un sottoinsieme di righe da elaborare da parte di Dataform durante ogni esecuzione, aggiungi una clausola WHERE condizionale al file di definizione SQLX della tabella incrementale. Nella clausola WHERE, puoi specificare una condizione incrementale e una non incrementale. Dataform applica la condizione incrementale durante l'esecuzione della tabella senza un aggiornamento completo e la condizione non incrementale durante l'esecuzione con un aggiornamento completo.

Per configurare una tabella incrementale:

  1. Vai allo spazio di lavoro di sviluppo.
  2. Nel riquadro File, espandi definitions/.
  3. Apri un file SQLX di definizione di tabella incrementale.

  4. Inserisci una clausola WHERE nel seguente formato:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Sostituisci quanto segue:

    • SELECT_STATEMENT: l'istruzione SELECT che definisce la tabella

    • INCREMENTAL_CONDITION: la condizione specificata nella clausola WHERE per selezionare le righe da elaborare da parte di Dataform durante l'esecuzione della tabella senza un aggiornamento completo.

    • NON_INCREMENTAL_CONDITION: la condizione specificata nella clausola WHERE per selezionare le righe da elaborare da parte di Dataform durante l'esecuzione della tabella con un aggiornamento completo.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale che elabora in modo incrementale le righe della tabella productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

Il seguente esempio di codice mostra una tabella incrementale che crea uno snapshot della tabella productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Unire le righe in una tabella incrementale

Per assicurarti che una tabella incrementale contenga una sola riga corrispondente a una combinazione selezionata di colonne, imposta le colonne selezionate come uniqueKey per unire le righe che hanno lo stesso uniqueKey. Quando aggiorni la tabella, Dataform unisce le righe con uniqueKey anziché aggiungerle.

Per configurare l'unione in una tabella incrementale:

  1. Vai allo spazio di lavoro di sviluppo.
  2. Nel riquadro File, espandi definitions/.
  3. Seleziona un file SQLX di definizione della tabella incrementale

  4. Nel blocco config, imposta le colonne selezionate come uniqueKey nel seguente formato:

    uniqueKey: ["COLUMN_NAME"]

    Sostituisci COLUMN_NAME con il nome di una colonna selezionata.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale con la colonna transaction_id impostata su uniqueKey per garantire che contenga sempre una riga:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Filtrare le righe di una tabella incrementale

In una tabella partizionata incrementale, per evitare che Dataform esamini tutta la tabella per trovare le righe corrispondenti, imposta updatePartitionFilter in modo da considerare solo un sottoinsieme di record.

Il seguente esempio di codice mostra una tabella partizionata incrementale con l'unione configurata impostando le proprietà uniqueKey e updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Evitare le scansioni complete della tabella durante l'importazione da una tabella partizionata

Quando crei una tabella incrementale che fa riferimento a una tabella partizionata, consigliamo di creare la query della tabella per evitare le scansioni complete della tabella partizionata durante ogni aggiornamento incrementale.

Puoi limitare il numero di partizioni sottoposte a scansione da parte di BigQuery per aggiornare la tabella incrementale utilizzando un'espressione costante nella query della tabella. Per trasformare un valore della tabella partizionata in un'espressione costante, utilizza gli script BigQuery per dichiarare il valore come variabile nel blocco pre_operations. Poi, utilizza la variabile come espressione costante in una clausola WHERE nella query SELECT.

Con questa configurazione, Dataform aggiorna la tabella incrementale in base alle partizioni più recenti della tabella partizionata a cui si fa riferimento, senza eseguire la scansione dell'intera tabella.

Per configurare una tabella incrementale che fa riferimento a una tabella partizionata ed evita le scansioni complete della tabella:

  1. Vai allo spazio di lavoro di sviluppo.
  2. Nel riquadro File, espandi definitions/.
  3. Seleziona un file SQLX di definizione della tabella incrementale
  4. Nel blocco pre_operations, dichiara una variabile con lo scripting BigQuery.
  5. Filtra l'istruzione SELECT che definisce la tabella con una clausola WHERE che fa riferimento alla variabile dichiarata.
  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale in cui la tabella raw_events a cui si fa riferimento è suddivisa in base a event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

Nell'esempio di codice precedente, la variabile event_timestamp_checkpoint è definita nel blocco pre_operations. La variabile event_timestamp_checkpoint viene poi utilizzata come espressione costante nella clausola WHERE.

Ricostruire una tabella incrementale da zero con aggiornamento completo

Puoi forzare la ricostruzione da zero di una tabella incrementale utilizzando l'interfaccia a riga di comando con l'opzione --full-refresh o l'opzione Esegui con aggiornamento completo quando attivi un'esecuzione del flusso di lavoro.

Quando selezioni l'opzione di aggiornamento completo, nello spazio di lavoro di sviluppo o utilizzando il client CLI Dataform, Dataform ignora il parametro ${when(incremental(), ... } durante l'esecuzione e ricrea la tabella con un'istruzione CREATE OR REPLACE.

Proteggere una tabella incrementale dall'aggiornamento completo

Per proteggere una tabella incrementale dalla ricostruzione da zero e dalla potenziale perdita di dati, puoi impostarla come protected. Ti consigliamo di impedire la ricostruzione di una tabella incrementale se l'origine dati è temporanea.

Per contrassegnare una tabella incrementale come protected:

  1. Vai allo spazio di lavoro di sviluppo.
  2. Nel riquadro File, espandi definitions/.
  3. Seleziona un file SQLX di definizione della tabella incrementale.
  4. Nel blocco config, inserisci protected: true.
  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale contrassegnata come protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Passaggi successivi