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:
table
: una tabella normale.incremental
: una tabella incrementale.view
: una visualizzazione tabella. Per ulteriori informazioni, consulta la sezione Introduzione alle visualizzazioni.materialized
: una vista tabella materializzata. Per ulteriori informazioni, consulta Introduzione alle viste tabelle materializzate.
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
oschema
. - 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
Nella console Google Cloud, vai alla pagina Dataform.
Crea e inizializza uno spazio di lavoro di sviluppo nel tuo repository.
(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:
- Tabelle di tutti i tipi di tabelle supportati.
- Dichiarazioni delle origini dati.
- Operazioni SQL personalizzate con la proprietà
hasOutput
impostata sutrue
.
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/
:
Nella console Google Cloud, vai alla pagina Dataform.
Per aprire un repository, fai clic sul nome del repository.
Per aprire uno spazio di lavoro di sviluppo, fai clic sul nome dello spazio.
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
dopodefinitions/
. 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 di tipo di tabella:
- Nell'area di lavoro di sviluppo, espandi la directory
definitions/
nel riquadro File. - Seleziona il file SQLX di definizione della tabella da modificare.
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
(Facoltativo) Per definire una vista materializzata, inserisci la proprietà
materialized
intype: "view"
nel seguente formato:config { type: "view", materialized: true }
Per ulteriori informazioni, 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, espandi la directory
definitions/
nel riquadro File. - Seleziona il file SQLX di definizione della tabella da modificare.
- Sotto il blocco
config
, scrivi un'istruzioneSELECT
. - (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:
- Nell'area di lavoro di sviluppo, espandi la directory
definitions/
nel riquadro File. - Seleziona il file SQLX di definizione della tabella da 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 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" ] }
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:
- Vai allo spazio di lavoro di sviluppo.
- Nel riquadro File, espandi
definitions/
. - Apri un file SQLX di definizione della tabella.
Nel blocco
config
, aggiungi il bloccobigquery
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 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:
- Vai allo spazio di lavoro 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 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:
- Vai allo spazio di lavoro 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 allo spazio di lavoro 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 ulteriori 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 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:
- Vai allo spazio di lavoro 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 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.
- SELECT_STATEMENT: l'istruzione
(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:
- Vai allo spazio di lavoro di sviluppo.
- Nel riquadro File, espandi
definitions/
. - Seleziona un file SQLX di definizione della tabella incrementale
Nel blocco
config
, imposta le colonne selezionate comeuniqueKey
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 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:
- Vai allo spazio di lavoro di sviluppo.
- Nel riquadro File, espandi
definitions/
. - Seleziona un file SQLX di definizione della tabella incrementale
- Nel blocco
pre_operations
, dichiara una variabile con lo scripting BigQuery. - Filtra l'istruzione
SELECT
che definisce la tabella con una clausolaWHERE
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 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
:
- Vai allo spazio di lavoro di sviluppo.
- Nel riquadro File, espandi
definitions/
. - Seleziona un file SQLX di definizione della tabella incrementale.
- Nel blocco
config
, inserisciprotected: 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, 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:
Nella console Google Cloud, vai alla pagina Dataform.
Seleziona un repository.
Seleziona uno spazio di lavoro di sviluppo.
Nel riquadro File, fai clic sul file SQLX di definizione della tabella da 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 record a un file SQLX, segui questi passaggi:
- Nel blocco
config
del file di definizione della tabella, inseriscicolumns: {}
. 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 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.
- 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 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
- Per scoprire come configurare impostazioni aggiuntive per le tabelle, consulta Configurare impostazioni aggiuntive per le tabelle.
- Per scoprire come testare i dati della tabella con le asserzioni, consulta Testare le tabelle con le asserzioni.
- Per scoprire come definire le tabelle con JavaScript, consulta Creare flussi di lavoro Dataform 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 l'interfaccia a riga di comando di Dataform.