Questa pagina è stata tradotta dall'API Cloud Translation.

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 tuo flusso di lavoro o di altre tabelle nel 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.

Puoi creare i seguenti tipi di tabelle in un file SQLX type: "table":

table: una tabella normale.
incremental: una tabella incrementale.
view: una visualizzazione tabella. Per saperne di più, consulta Introduzione alle visualizzazioni.
- materialized: una vista materializzata della tabella. Per saperne di più, consulta Introduzione alle viste materializzate.

Puoi anche definire le partizioni e i cluster della tabella.

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

Per testare i dati in una tabella in base a condizioni specifiche, puoi creare query di test della qualità dei dati chiamate asserzioni. Dataform esegue le asserzioni ogni volta che aggiorna il flusso di lavoro e ti avvisa se una qualsiasi asserzione non va a buon fine.

Per eseguire l'override dello schema, del database e del nome predefiniti di una tabella selezionata, puoi eseguire l'override delle impostazioni della tabella.

Per disattivare la creazione di tabelle o eseguire un'istruzione SQL prima o dopo la creazione di tabelle, puoi configurare azioni aggiuntive.

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

Per limitare l'accesso ai dati a livello di colonna della tabella, puoi aggiungere 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 voler creare una tabella vuota in modo che un altro servizio possa compilarla con i dati.

Prima di iniziare

Nella console Google Cloud , vai alla pagina Dataform.

Vai a Dataform
Crea e inizializza un workspace di sviluppo nel repository.
(Facoltativo) Dichiara un'origine dati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti il ruolo IAM Editor Dataform (roles/dataform.editor) sugli 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.

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 il codice Dataform Core in SQL, esegue il codice SQL e crea le tabelle definite in BigQuery.

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

Oltre a definire le tabelle in un file type: "table" SLQX, puoi creare tabelle vuote definendo una query SQL personalizzata in un file type: "operations" SQLX. Per saperne di più, vedi Creare una tabella vuota.

Riferimento alle dipendenze con `ref`

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

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

Tabelle di tutti i tipi di tabella supportati.
Dichiarazioni dell'origine dati.
Operazioni SQL personalizzate con la proprietà hasOutput impostata su true.

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 tabella o della dichiarazione 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, vedi Ignorare le impostazioni della tabella e Fare riferimento a una tabella con un nome tabella ignorato.

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, asserzioni, dichiarazioni di origini dati o operazioni SQL personalizzate che non sono riferite in una funzione ref nell'istruzione SELECT. Dataform esegue queste dipendenze prima delle tabelle dipendenti.

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

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

Per ulteriori informazioni sulla gestione delle dipendenze nel flusso di lavoro, vedi Impostare le dipendenze.

Fai 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 viene fatto riferimento utilizzando la funzione resolve non influisce sull'esecuzione della tabella che utilizza la funzione resolve.

Per saperne di più sulle funzioni core integrate di Dataform, consulta la documentazione di riferimento di Dataform Core.

Crea un file SQLX per una definizione di tabella

Archivia i file SQLX di definizione delle tabelle nella directory definitions/. Per creare un nuovo file SQLX nella directory definitions/, segui questi passaggi:

Nella console Google Cloud , vai alla pagina Dataform.

Vai a Dataform
Per aprire un repository, fai clic sul relativo nome.
Per aprire un'area di lavoro di sviluppo, fai clic sul relativo nome.
Nel riquadro File, accanto a definitions/, fai clic su Altro.
Fai clic su Crea file.
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.
Fai clic su Crea file.

Definisci il tipo di tabella

Per creare una nuova definizione del tipo di tabella:

Nell'area di lavoro di sviluppo, nel riquadro File, espandi la directory definitions/.
Seleziona il file SQLX di definizione della tabella che vuoi modificare.
Nel file, inserisci il seguente snippet di codice:
```
config { type: "TABLE_TYPE" }
```
Sostituisci TABLE_TYPE con uno dei seguenti tipi di tabella:
- table
- incremental
- view
(Facoltativo) Per definire una vista materializzata, inserisci la proprietà materialized in type: "view" nel seguente formato:
```
config {
  type: "view",
  materialized: true
}
```
Per saperne di più, consulta ITableConfig.
(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:

Nell'area di lavoro di sviluppo, nel riquadro File, espandi la directory definitions/.
Seleziona il file SQLX di definizione della tabella che vuoi modificare.
Sotto il blocco config, scrivi una dichiarazione SELECT.
(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 manuali delle tabelle

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

Nell'area di lavoro di sviluppo, nel riquadro File, espandi la directory definitions/.
Seleziona il file SQLX di definizione della tabella che vuoi modificare.
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 di file.
(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" ] }

Esegui l'override delle impostazioni della tabella

Puoi eseguire l'override dello schema, del database e del nome predefiniti di una tabella selezionata.

Per impostazione predefinita, una tabella segue la configurazione dello schema e del database impostata in workflow_settings.yaml. Il nome di una tabella corrisponde al nome del file SQLX di definizione della tabella.

Per ignorare lo schema e il nome di una tabella selezionata:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file di definizione della tabella SQLX.
Nel blocco config, inserisci il seguente snippet di codice:
```
 {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }
```
Sostituisci quanto segue:
- OVERRIDDEN_SCHEMA: il set di dati BigQuery in cui vuoi creare la tabella.
- OVERRIDDEN_DATABASE: l'ID del progetto BigQuery in cui vuoi creare la tabella.
- OVERRIDDEN_NAME: il nome della tabella, diverso dal nome del file di definizione della tabella SQLX.
(Facoltativo) Fai clic su Formato.

Per ulteriori informazioni, consulta Fare riferimento a una tabella con un nome tabella sottoposto a override.

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, vedi Introduzione alle tabelle partizionate e Creazione e utilizzo di tabelle in cluster.

Creare una partizione di tabella

Per creare una partizione della tabella:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file SQLX di definizione della tabella.
Nel blocco config, aggiungi il blocco bigquery sotto la dichiarazione del tipo di tabella nel seguente formato:
```
config {
  type: "table",
  bigquery: {
  }
}
```
Nel blocco bigquery, inserisci il seguente snippet di codice:
```
    partitionBy: "PARTITION_EXPRESSION"
```
Sostituisci PARTITION_EXPRESSION con un'espressione per il partizionamento della tabella.
(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 il partizionamento 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 partizionamento

Per impostare un filtro di partizione:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file SQLX di definizione di una tabella partizionata.
Nel blocco bigquery, inserisci il seguente snippet di codice:
```
requirePartitionFilter : true
```
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un filtro di partizione impostato nel blocco bigquery di un file SQLX di una 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 di filtro di partizione obbligatorio in 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:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file SQLX di definizione di una tabella partizionata.
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.
(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:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file SQLX di definizione della tabella.
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 maggiori informazioni, consulta clustering_column_list.
(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 ricompila 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 solo le nuove righe nella tabella incrementale 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 ricompilare la tabella da zero. Per farlo, la prossima volta 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 in modo rapido ma frequente, riducendo la latenza a valle delle tabelle di output.
Snapshot giornalieri: 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.

Elabora un sottoinsieme di righe in una tabella incrementale

Per determinare un sottoinsieme di righe da elaborare 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:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Apri un file SQLX di definizione della tabella incrementale.
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 deve elaborare durante l'esecuzione della tabella senza un aggiornamento completo.
- NON_INCREMENTAL_CONDITION: la condizione specificata nella clausola WHERE per selezionare le righe che Dataform deve elaborare durante l'esecuzione della tabella con un aggiornamento completo.
(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 verificare che una tabella incrementale contenga una sola riga corrispondente a una combinazione di colonne selezionata, 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:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Seleziona un file SQLX di definizione della tabella incrementale
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.
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale con la colonna transaction_id impostata su uniqueKey per verificare 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 esegua la scansione dell'intera tabella per trovare le righe corrispondenti, imposta updatePartitionFilter in modo che prenda in considerazione 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 le 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 la query della tabella in modo da evitare scansioni complete della tabella partizionata durante ogni aggiornamento incrementale.

Puoi limitare il numero di partizioni analizzate da 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 BigQuery Scripting 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 viene fatto riferimento, senza scansionare l'intera tabella.

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

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Seleziona un file SQLX di definizione della tabella incrementale
Nel blocco pre_operations, dichiara una variabile con gli script BigQuery.
Filtra l'istruzione SELECT che definisce la tabella con una clausola WHERE che fa riferimento alla variabile dichiarata.
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una tabella incrementale in cui la tabella raw_events a cui viene fatto riferimento è partizionata 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 quindi utilizzata come espressione costante nella clausola WHERE.

Ricrea una tabella incrementale da zero con l'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 attivi l'esecuzione di un flusso di lavoro.

Quando selezioni l'opzione di aggiornamento completo, nello spazio di lavoro di sviluppo o utilizzando la 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 ricreazione da zero e dalla potenziale perdita di dati, puoi impostare la tabella incrementale come protected. Potresti voler impedire la ricostruzione di una tabella incrementale se l'origine dati è temporanea.

Per contrassegnare una tabella incrementale come protected:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Seleziona un file SQLX di definizione della tabella incrementale.
Nel blocco config, inserisci protected: true.
(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 e delle relative colonne e 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 viste.

Ti consigliamo di documentare quanto segue:

Lo scopo della tabella.
Il contenuto o il ruolo di colonne o record nella tabella.
La relazione tra la tabella e le altre azioni del flusso di lavoro, ad esempio le tabelle o le viste che dipendono dalla tabella corrente.
Le asserzioni applicate alla tabella.
Le operazioni pre o post 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 a un flusso di lavoro.

Aggiungere una descrizione della tabella

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

Nella console Google Cloud , vai alla pagina Dataform.

Vai a Dataform
Seleziona un repository.
Seleziona un'area di lavoro di sviluppo.
Nel riquadro File, fai clic sul file SQLX di definizione della tabella che vuoi modificare.
Nel blocco config del file, inserisci la descrizione della tabella nel seguente formato:
```
description: "Description of the table",
```
(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 singoli record a un file SQLX:

Nel blocco config del file di definizione della tabella, inserisci columns: {}.
All'interno di columns: {}, inserisci le descrizioni delle colonne nel seguente formato:
```
column_name: "Description of the column",
```

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

(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 include

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

Per creare una descrizione della colonna riutilizzabile, definisci una costante di inclusione JavaScript con il nome della colonna e la relativa descrizione.

Puoi definire una costante con la descrizione di una singola colonna o una costante con un insieme o una descrizione di colonna per riutilizzare le descrizioni di tutte le colonne di una tabella. Per ulteriori informazioni sulla creazione e l'utilizzo di 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

Aggiungere etichette BigQuery

Questa sezione mostra come aggiungere etichette alle tabelle in Dataform.

BigQuery supporta l'aggiunta di etichette alle risorse. Per ulteriori informazioni sulle etichette in BigQuery, vedi Introduzione alle etichette.

Per aggiungere un'etichetta BigQuery a una tabella in Dataform, aggiungi l'etichetta al blocco bigquery nel blocco config del file SQLX di definizione della tabella.

Per aggiungere un'etichetta BigQuery a un file di definizione della tabella:

Vai al tuo workspace di sviluppo.
Nel riquadro File, espandi definitions/.
Seleziona un file di definizione della tabella SQLX.
Nel blocco config, aggiungi un'etichetta nel seguente formato:
```
bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }
```
Sostituisci quanto segue:
- LABEL1: il nome dell'etichetta
- VALUE_OF_LABEL1: il valore dell'etichetta
(Facoltativo) Per aggiungere un'etichetta con un nome che contiene caratteri speciali, inserisci il nome dell'etichetta tra virgolette ("").
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra le etichette department:shipping e cost-center:logistics aggiunte al blocco bigquery in un file SQLX di definizione della tabella partizionata:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

Passaggi successivi

Per scoprire come testare i dati delle tabelle con le asserzioni, consulta Testare la qualità dei dati.
Per scoprire come definire le tabelle con JavaScript, consulta Crea flussi di lavoro esclusivamente con JavaScript.
Per scoprire come riutilizzare il codice con gli include, consulta Riutilizzare il codice in un singolo repository con gli include.
Per scoprire come utilizzare l'interfaccia a riga di comando di Dataform, consulta Utilizzare la CLI di Dataform.

Creare tabelle Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.