Questo documento mostra come definire le 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 SQL.
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 SQL 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 integrata di base 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 Dataform SQL 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 come
CREATE
, REPLACE
, INSERT
o MERGE
all'istruzione SQL.
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 SQL, 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 resolve
non influisce sull'esecuzione della tabella che utilizza resolve
.
Per ulteriori informazioni sulle funzioni di base di Dataform integrate, consulta la documentazione di riferimento di Dataform.
Prima di iniziare
- 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 definire una tabella,
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.
Crea un file SQLX per definire una tabella
Memorizza i file SQLX di definizione delle tabelle nella directory definitions/
. Per creare un
nuovo file SQLX nella directory definitions/
, segui questi passaggi:
Nella console 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 sul menu 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 che vuoi 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 la pagina
ITableConfig
Documentazione di riferimento di Dataform.(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 che vuoi 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 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 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" ] }
Passaggi successivi
- Per scoprire come configurare le tabelle incrementali, consulta Configurare le tabelle incrementali.
- Per scoprire come configurare partizioni e cluster di tabelle, consulta Creare partizioni e cluster di tabelle.
- Per scoprire come aggiungere la documentazione alle tabelle, consulta Aggiungere la documentazione delle 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 configurare impostazioni aggiuntive per le tabelle, consulta Configurare impostazioni aggiuntive per le tabelle.