Creare tabelle

In Dataform, una tabella è uno dei tipi di oggetti che compongono un workflow. Puoi creare tabelle che fanno riferimento ai dati delle origini dati dichiarate per il flusso di lavoro o di altre tabelle del flusso di lavoro. Dataform compila le definizioni delle tabelle in SQL in tempo reale. Quando attivi l'esecuzione, Dataform esegue il codice SQL e crea le tabelle definite in BigQuery.

In un file SQLX type: "table" puoi creare i seguenti tipi di tabelle:

Puoi anche definire partizioni e cluster della tabella.

Per tenere traccia dello scopo di una tabella o della sua relazione con altre tabelle nel tuo flusso di lavoro, puoi aggiungere documentazione alla tabella o alle sue colonne selezionate.

Per verificare i dati di una tabella in base a condizioni specifiche, puoi creare query di test della qualità dei dati chiamate asserzioni. Dataform esegue le verifiche ogni volta che aggiorna il flusso di lavoro e ti avvisa in caso di errori.

Per eseguire l'override delle impostazioni predefinite della tabella, ad esempio database o schema, e disattivare la creazione della tabella o eseguire un'istruzione SQL prima o dopo la creazione della tabella, puoi configurare impostazioni aggiuntive della tabella.

Puoi configurare impostazioni aggiuntive della tabella per:

  • Sostituisci le impostazioni predefinite della tabella, ad esempio database o schema.
  • Disattiva la creazione della tabella.
  • Esegui un'istruzione SQL prima o dopo la creazione della tabella.

Per organizzare le tabelle in BigQuery dopo averle eseguite, puoi aggiungere etichette BigQuery. Per scoprire di più, consulta Introduzione alle etichette.

Per limitare l'accesso ai dati a livello di colonna della tabella, puoi aggiungere i tag di criteri BigQuery. Per saperne di più, consulta Introduzione al controllo dell'accesso a livello di colonna.

Oltre a definire le tabelle in un file SQLX type: "table", puoi creare tabelle vuote definendo una query SQL personalizzata in un file SQLX type: "operations". Potresti creare una tabella vuota in modo che un altro servizio possa compilarla con i dati.

Prima di iniziare

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

    Vai a Dataform

  2. Crea e inizializza uno spazio di lavoro di sviluppo nel tuo repository.

  3. (Facoltativo) Dichiara un'origine dati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività in questo documento, 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.

Creare una tabella

Questa sezione mostra come creare tabelle con Dataform Core in Dataform.

Informazioni sulle definizioni delle tabelle

Per definire una tabella, devi definire il tipo di tabella e scrivere un'istruzione SELECT in un file SQLX type: "table". Dataform compila quindi il codice di Dataform in SQL, esegue il codice SQL e crea le tabelle definite in BigQuery.

In un'istruzione SELECT di Dataform di base, definisci la struttura della tabella e fai riferimento ad altri oggetti del flusso di lavoro.

Oltre a definire le tabelle in un file SLQX type: "table", puoi creare tabelle vuote definendo una query SQL personalizzata in un file SQLX type: "operations". Per ulteriori informazioni, consulta Creare una tabella vuota.

Fare riferimento alle dipendenze con ref

Per fare riferimento a un oggetto del flusso di lavoro in un'istruzione SELECT e aggiungerlo automaticamente come dipendenza, utilizza la funzione ref. Dataform esegue le dipendenze prima delle tabelle che dipendono da queste per garantire l'ordinamento corretto della pipeline.

La funzione ref è una funzione di Dataform di base integrata che è fondamentale per la gestione delle dipendenze in Dataform. La funzione ref consente di fare riferimento e dipendere automaticamente dai seguenti oggetti definiti nel flusso di lavoro di Dataform, anziché codificare in modo rigido i nomi dello schema e delle tabelle:

Dataform utilizza la funzione ref per creare un albero delle dipendenze di tutte le tabelle da creare o aggiornare.

Dopo la compilazione, Dataform aggiunge istruzioni boilerplate all'istruzione SQL, ad esempio CREATE, REPLACE, INSERT o MERGE.

Il seguente esempio di codice mostra una definizione di tabella con l'utilizzo della funzione ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

Nella funzione ref, fornisci il nome della dichiarazione della tabella o dell'origine dati da cui vuoi dipendere. In genere si tratta del nome del file SQLX in cui è definita la dichiarazione della tabella o dell'origine dati.

Se il nome di una tabella viene sostituito, utilizza il nome sostituito nella funzione ref. Ad esempio, fai riferimento a una tabella con config { name: "overridden_name" } come ref("overridden_name"). Per ulteriori informazioni sull'override dei nomi delle tabelle, consulta Configurare impostazioni aggiuntive delle tabelle.

Quando hai più tabelle con lo stesso nome in schemi diversi, puoi fare riferimento a una tabella specifica fornendo due argomenti alla funzione ref: il nome dello schema e il nome della tabella.

Il seguente esempio di codice mostra la funzione ref con due argomenti per specificare una tabella all'interno di uno schema specifico:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Puoi anche aggiungere manualmente le dipendenze delle tabelle al blocco config per tabelle, assert, dichiarazioni di origini dati o operazioni SQL personalizzate a cui non viene fatto riferimento in una funzione ref nell'istruzione SELECT. Dataform esegue queste dipendenze prima delle tabelle dipendenti.

Il seguente esempio di codice mostra una dipendenza da tabella nel blocco config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Per ulteriori informazioni sulla gestione delle dipendenze nel flusso di lavoro, consulta Dichiarare le dipendenze.

Fare riferimento ad altre tabelle con resolve

La funzione resolve consente di fare riferimento a una dichiarazione di tabella o origine dati in un'istruzione SELECT come la funzione ref, ma non aggiunge il riferimento come dipendenza. Ciò significa che l'oggetto a cui si fa riferimento utilizzando la funzione resolve non influisce sull'esecuzione della tabella che utilizza la funzione resolve.

Per ulteriori informazioni sulle funzioni di base di Dataform integrate, consulta Riferimento di Dataform Core.

Crea un file SQLX per una definizione di tabella

Memorizza i file SQLX di definizione delle tabelle nella directory definitions/. Per creare un nuovo file SQLX nella directory definitions/:

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

    Vai a Dataform

  2. Per aprire un repository, fai clic sul nome del repository.

  3. Per aprire uno spazio di lavoro di sviluppo, fai clic sul nome dello spazio.

  4. Nel riquadro File, accanto a definitions/, fai clic su Altro.

  5. Fai clic su Crea file.

  6. Nel campo Aggiungi un percorso del file, inserisci il nome del file seguito da .sqlx dopo definitions/. Ad esempio: definitions/my-table.sqlx.

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

  7. Fai clic su Crea file.

Definisci il tipo di tabella

Per creare una nuova definizione di tipo di tabella:

  1. Nell'area di lavoro di sviluppo, espandi la directory definitions/ nel riquadro File.
  2. Seleziona il file SQLX di definizione della tabella da modificare.

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

    config { type: "TABLE_TYPE" }

    Sostituisci TABLE_TYPE con uno dei seguenti tipi di tabelle:

    • table
    • incremental
    • view

  4. (Facoltativo) Per definire una vista materializzata, inserisci la proprietà materialized in type: "view" nel seguente formato:

    config {
  type: "view",
  materialized: true
}

    Per ulteriori informazioni, consulta ITableConfig.

  5. (Facoltativo) Fai clic su Formato.

Definisci la struttura e le dipendenze della tabella

Per scrivere un'istruzione SELECT di definizione della tabella e definire la struttura e le dipendenze della tabella:

  1. Nell'area di lavoro di sviluppo, espandi la directory definitions/ nel riquadro File.
  2. Seleziona il file SQLX di definizione della tabella da modificare.
  3. Sotto il blocco config, scrivi un'istruzione SELECT.
  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una definizione di tabella con un'istruzione SELECT e la funzione ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Aggiungere dipendenze delle tabelle manuali

Per aggiungere dipendenze di tabelle a cui non viene fatto riferimento nell'istruzione SELECT, ma che devono essere eseguite prima della tabella corrente:

  1. Nell'area di lavoro di sviluppo, espandi la directory definitions/ nel riquadro File.
  2. Seleziona il file SQLX di definizione della tabella da modificare.

  3. Nel blocco config della tabella, inserisci il seguente snippet di codice:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Sostituisci DEPENDENCY_TABLE con il nome file della tabella che vuoi aggiungere come dipendenza. Puoi inserire più nomi file.

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra due tabelle aggiunte come dipendenze manuali al blocco config di un file di definizione della tabella:

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

Crea partizioni e cluster di tabelle

Questa sezione mostra come utilizzare Dataform core per creare partizioni e cluster di tabelle. BigQuery supporta le tabelle partizionate e il clustering delle tabelle. Per ulteriori informazioni, consulta Introduzione alle tabelle partizionate e Creare e utilizzare tabelle clusterizzate.

Creare una partizione della tabella

Per creare una partizione di tabella:

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

  4. Nel blocco config, aggiungi il blocco bigquery sotto la dichiarazione del tipo di tabella nel seguente formato:

    config {
  type: "table",
  bigquery: {
  }
}

  5. Nel blocco bigquery, inserisci il seguente snippet di codice:

        partitionBy: "PARTITION_EXPRESSION"

    Sostituisci PARTITION_EXPRESSION con un'espressione per il partizionamento della tabella.

  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra il partizionamento di una tabella per ora in un file SQLX di definizione della tabella:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

Il seguente esempio di codice mostra la suddivisione di una tabella in base a un valore intero in un file SQLX di definizione della tabella:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Impostare un filtro di partizione

Per impostare un filtro della partizione:

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

  4. Nel blocco bigquery, inserisci il seguente snippet di codice:

    requirePartitionFilter : true

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un filtro partizione impostato nel blocco bigquery di un file SQLX della tabella partizionata:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Per ulteriori informazioni sul filtro di partizione in BigQuery, consulta Impostare l'attributo require partition filter su una tabella partizionata.

Impostare un periodo di conservazione per le partizioni

Per controllare la conservazione di tutte le partizioni in una tabella partizionata, segui questi passaggi:

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

  4. Nel blocco bigquery, inserisci il seguente snippet di codice:

    partitionExpirationDays: NUMBER_OF_DAYS

    Sostituisci NUMBER_OF_DAYS con il numero di giorni per i quali vuoi conservare le partizioni.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un periodo di conservazione per le partizioni impostato su 14 giorni nel blocco bigquery di un file SQLX della tabella partizionata:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Creare un cluster di tabelle

Per creare un cluster di tabelle:

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

  4. Nel blocco bigquery, inserisci il seguente snippet di codice:

        clusterBy: ["CLUSTER_COLUMN"]

    Sostituisci CLUSTER_COLUMN con il nome della colonna in base alla quale vuoi raggruppare la tabella. Per ulteriori informazioni, consulta clustering_column_list.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella partizionata raggruppata in cluster in base alle colonne name e revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Configurare una tabella incrementale

Questa sezione mostra come utilizzare Dataform core per configurare una tabella incrementale.

Informazioni sulle tabelle incrementali

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 aggiungendo una nuova colonna, devi ricostruire la tabella da zero. A questo scopo, 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.

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 condizione 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 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 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 valore uniqueKey. Quando aggiorni la tabella, Dataform unisce le righe con lo stesso valore 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, ti consigliamo di creare la query della tabella per evitare 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 evitare 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 ...

Aggiungere la documentazione della tabella

Questa sezione mostra come aggiungere descrizioni di una tabella, delle relative colonne e dei relativi record a un file SQLX di Dataform Core.

Puoi aggiungere descrizioni di tabelle, colonne e record a tutti i tipi di tabelle in Dataform: tabelle, tabelle incrementali e visualizzazioni.

Ti consigliamo di documentare quanto segue:

  • Lo scopo della tabella.
  • I contenuti o il ruolo delle colonne o dei record nella tabella.
  • La relazione tra la tabella e altre azioni del flusso di lavoro, ad esempio le tabelle o le visualizzazioni che dipendono dalla tabella corrente.
  • Le asserzioni applicate alla tabella.
  • Le operazioni preliminari o successive applicate alla tabella.
  • Il proprietario della tabella, ovvero l'utente che l'ha creata. Queste informazioni potrebbero essere utili se più membri del team lavorano su un flusso di lavoro.

Aggiungere una descrizione della tabella

Per aggiungere una descrizione a una tabella in un file SQLX:

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

    Vai a Dataform

  2. Seleziona un repository.

  3. Seleziona uno spazio di lavoro di sviluppo.

  4. Nel riquadro File, fai clic sul file SQLX di definizione della tabella da modificare.

  5. Nel blocco config del file, inserisci la descrizione della tabella nel seguente formato:

    description: "Description of the table",

  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una descrizione della tabella aggiunta al blocco config di un file di definizione della tabella SQLX:

config {
  type: "table",
  description: "Description of the table",
 }

Aggiungere descrizioni di colonne e record

Per aggiungere descrizioni di singole colonne e record a un file SQLX, segui questi passaggi:

  1. Nel blocco config del file di definizione della tabella, inserisci columns: {}.

  2. All'interno di columns: {}, inserisci le descrizioni delle colonne nel seguente formato:

    column_name: "Description of the column",

  3. All'interno di columns: {}, inserisci le descrizioni dei record nel seguente formato:

      record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra le descrizioni di tabelle, colonne e record nel blocco config di un file di definizione della tabella SQLX:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Riutilizzare la documentazione delle colonne con gli elementi inclusi

Puoi riutilizzare le descrizioni delle colonne in Dataform nel flusso di lavoro SQL con le inclusioni JavaScript. Ti consigliamo di riutilizzare la documentazione delle colonne se nel flusso di lavoro SQL hai più colonne con lo stesso nome e la stessa descrizione.

Puoi definire una costante con una descrizione di una singola colonna o una costante con una descrizione di un insieme o di una colonna per riutilizzare le descrizioni di tutte le colonne di una tabella. Per ulteriori informazioni sulla creazione e sull'utilizzo degli include in Dataform, consulta Riutilizzare il codice in un singolo repository con gli include.

Il seguente esempio di codice mostra più costanti con descrizioni di singole colonne definite nel file JavaScript includes/docs.js:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

Il seguente esempio di codice mostra le costanti user_id e age, definite in includes/docs.js, utilizzate nel file di definizione della tabella SQLX definitions/my_table.sqlx per generare la documentazione per le colonne selezionate della tabella:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

Il seguente esempio di codice mostra una costante con un insieme di descrizioni delle colonne definite nel file JavaScript includes/docs.js:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

Il seguente esempio di codice mostra la costante columns, definita in includes/table_docs.js e utilizzata nel file di definizione della tabella SQLX definitions/my_table.sqlx per generare la documentazione per tutte le colonne della tabella:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

Passaggi successivi