Configurare una tabella incrementale

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

Informazioni su una tabella incrementale

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

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

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 ricreare 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, potrebbe essere utile elaborare solo i nuovi record anziché rielaborare l'intera tabella.
Riduzione della latenza
Puoi utilizzare tabelle incrementali per eseguire flussi di lavoro rapidamente ma frequentemente, riducendo la latenza downstream delle tabelle di output.
Istantanee giornaliere
Puoi configurare una tabella incrementale per creare snapshot giornalieri dei dati della tabella, ad esempio per l'analisi longitudinale delle impostazioni utente archiviate 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 di tipo incremental.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare una tabella incrementale, chiedi all'amministratore di concederti il ruolo IAM 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 i ruoli personalizzati o altri ruoli predefiniti.

Elabora un sottoinsieme di righe in una tabella incrementale

Per determinare un sottoinsieme di righe che Dataform elaborerà 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 all'area di lavoro di sviluppo.
  2. Nel riquadro File, espandi definitions/.
  3. Apri un file SQLX di definizione della 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 che Dataform elaborerà durante l'esecuzione della tabella senza un aggiornamento completo.

    • NON_INCREMENTAL_CONDITION: la condizione specificata nella clausola WHERE per selezionare le righe che Dataform elaborerà 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()})`) }

Unisci le righe in una tabella incrementale

Per garantire che una tabella incrementale contenga una sola riga corrispondente a una combinazione di colonne selezionata, imposta le colonne selezionate su uniqueKey per unire le righe che hanno lo stesso uniqueKey. Durante l'aggiornamento della tabella, Dataform unisce le righe con uniqueKey anziché aggiungerle.

Per configurare l'unione in una tabella incrementale:

  1. Vai all'area 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 in una tabella incrementale

In una tabella partizionata incrementale, per evitare che Dataform analizzi l'intera tabella per trovare righe corrispondenti, imposta updatePartitionFilter in modo da considerare solo un sottoinsieme di record.

Il seguente esempio di codice mostra una tabella partizionata incrementale con 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()})`) }

Evita scansioni complete delle tabelle durante l'importazione da una tabella partizionata

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

Puoi limitare il numero di partizioni che BigQuery analizza 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 lo scripting BigQuery per dichiarare il valore come variabile nel blocco pre_operations. Poi, utilizza la variabile come espressione costante in una clausola WHERE della query SELECT.

Con questa configurazione, Dataform aggiorna la tabella incrementale in base alle partizioni più recenti della tabella partizionata di riferimento, senza analizzare l'intera tabella.

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

  1. Vai all'area 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, dichiari 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 di riferimento è partizionata per 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 quindi utilizzata come espressione costante nella clausola WHERE.

Ricrea una tabella incrementale da zero con aggiornamento completo

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

Quando selezioni l'opzione di aggiornamento completo, nell'area di lavoro di sviluppo o utilizzando l'interfaccia a riga di comando di 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 ricreazione da zero e dalla potenziale perdita di dati, puoi impostare la tabella incrementale come protected. Se l'origine dati è temporanea, potrebbe essere opportuno impedire la ricreazione di una tabella incrementale.

Per contrassegnare una tabella incrementale come protected:

  1. Vai all'area 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