Questo documento descrive le best practice per la strutturazione e la denominazione dei file di flusso di lavoro SQL nella directory principale definitions di un repository Dataform. La struttura consigliata della directory definitions riflette le fasi di un flusso di lavoro SQL. Puoi adottare qualsiasi struttura adatta alle esigenze della tua attività.
Ti consigliamo di strutturare il codice del flusso di lavoro SQL
nella directory definitions per i seguenti motivi:
- Migliorare la collaborazione sulla base di codice designando i team per parti selezionate del flusso di lavoro.
- Migliora la manutenibilità del flusso di lavoro SQL in caso di modifiche organizzative.
- Migliorare la navigazione nella base di codice.
- Migliorare la scalabilità della base di codice.
- Riduci al minimo l'overhead amministrativo per il tuo team.
Struttura consigliata della directory definitions
La directory principale definitions in un repository Dataform contiene il codice che crea gli elementi del tuo flusso di lavoro SQL. Puoi organizzare
i file nella directory definitions in una struttura di directory
che rispecchi la struttura del flusso di lavoro.
Quando sviluppi un flusso di lavoro SQL, dichiari le tabelle di origine e le trasformi per creare tabelle di output che puoi utilizzare per scopi aziendali o di analisi.
Puoi distinguere tre fasi chiave di un flusso di lavoro SQL:
- Dichiarazione delle origini dati
- Trasformazione dei dati di origine
- Definizione delle tabelle di output dai dati di origine trasformati
La seguente struttura di sottodirectory nella directory definitions riflette le fasi chiave di un flusso di lavoro SQL:
sources- Dichiarazioni delle origini dati e trasformazione di base dei dati di origine, ad esempio i filtri.
intermediate- Tabelle e azioni che leggono da
sourcese trasformano i dati prima di utilizzarli per definire le tabelleoutputs. Le tabelle in genere non esposte a processi o strumenti aggiuntivi, come gli strumenti di business intelligence (BI), dopo che Dataform le esegue in BigQuery. outputs- Definizioni delle tabelle utilizzate da processi o strumenti, come la BI, dopo che Dataform le ha eseguite in BigQuery.
extra- File esterni alla pipeline principale del flusso di lavoro SQL, ad esempio i file che contengono i dati del flusso di lavoro preparati per un uso aggiuntivo, come il machine learning. Una sottodirectory facoltativa e personalizzata.
Best practice per sources
La sottodirectory sources contiene la prima fase del flusso di lavoro SQL: dichiarazione e trasformazione di base dei dati di origine.
Nella sottodirectory sources, archivia le dichiarazioni e le tabelle delle origini dati
che filtrano, classificano, trasmettono o rinominano le colonne.
Evita di archiviare tabelle che combinano dati di più origini.
Trasforma i dati sources nelle tabelle archiviate nella sottodirectory intermediate.
Se dichiari origini dati da più pool, ad esempio Google Ads o Google Analytics, assegna una sottodirectory a ogni pool.
L'esempio seguente mostra una struttura di sottodirectory di sources
con due pool di origini:
definitions/
sources/
google_ads/
google_ads_filtered.sqlx
google_ads_criteria_metrics.sqlx
google_ads_criteria_metrics_filtered.sqlx
google_ads_labels.sqlx
google_ads_labels_filtered.sqlx
google_analytics/
google_analytics_users.sqlx
google_analytics_users_filtered.sqlx
google_analytics_sessions.sqlx
Se dichiari più tabelle di origini dati nello stesso schema, puoi consolidare le relative dichiarazioni in un unico file JavaScript. a Per ulteriori informazioni sulla creazione di dichiarazioni delle origini dati con JavaScript, consulta Creare flussi di lavoro Dataform con JavaScript.
Il seguente esempio di codice mostra più origini dati all'interno di uno schema, dichiarate in un unico file JavaScript:
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
Per proteggere il flusso di lavoro SQL dalle modifiche dell'origine dati, puoi creare una vista per ogni dichiarazione dell'origine dati, ad esempio analytics_users_filtered.sqlx.
La visualizzazione può contenere filtri e formattazione di base dei dati di origine.
Memorizza le visualizzazioni nella sottodirectory sources.
Poi, quando crei tabelle intermediate o outputs, fai riferimento alle visualizzazioni instead of raw source tables. Questo approccio ti consente di testare le tabelle di origine.
Se una tabella di origine cambia, puoi modificarne la visualizzazione, ad esempio aggiungendo filtri o modificando i dati.
Best practice per intermediate
La sottodirectory intermediate contiene la seconda fase del flusso di lavoro SQL:
la trasformazione e l'aggregazione dei dati di origine da una o più origini.
Nella sottodirectory intermediate, archivia i file che trasformano in modo significativo i dati di origine di una o più origini nella sottodirectory sources, ad esempio le tabelle che uniscono i dati. Le tabelle nella sottodirectory intermediate solitamente eseguono query sui dati delle tabelle di origine o di altre tabelle intermediate.
Utilizza le tabelle intermediate per creare tabelle outputs.
In genere, le tabelle intermediate non vengono utilizzate per scopi aggiuntivi,
ad esempio
l'analisi dei dati, dopo che Dataform le esegue in BigQuery.
Puoi considerare le tabelle intermediate come la logica di trasformazione dei dati
che consente la creazione di tabelle di output.
Ti consigliamo di documentare e
testare tutte le tabelle intermediate.
Best practice per outputs
La sottodirectory outputs contiene la fase finale del flusso di lavoro SQL:
la creazione di tabelle di output per le tue finalità aziendali dai dati trasformati.
Nella directory outputs, archivia le tabelle che prevedi di utilizzare in processi o strumenti aggiuntivi dopo che Dataform le ha eseguite in BigQuery, ad esempio report o dashboard. In genere, le tabelle nella directory outputs eseguono query sui dati delle tabelle intermediate.
Raggruppa le tabelle outputs in base all'entità aziendale a cui sono correlate, ad esempio marketing, ordini o analisi. Dedica una sottodirectory a ogni entità aziendale.
Per archiviare le tabelle di output separatamente in BigQuery, puoi configurare uno schema dedicato per le tabelle di output. Per le istruzioni su come configurare lo schema della tabella, consulta Configurare impostazioni aggiuntive della tabella.
L'esempio seguente mostra una struttura di sottodirectory di outputs
con entità aziendali sales e marketing:
definitions/
outputs/
orders/
orders.sqlx
returns.sqlx
sales/
sales.sqlx
revenue.sqlx
marketing/
campaigns.sqlx
Ti consigliamo di documentare e
testare tutte le tabelle outputs.
Strategia di denominazione
I nomi di tutti i file in Dataform devono essere conformi alle linee guida per la denominazione delle tabelle BigQuery.
Ti consigliamo che i nomi dei file nella directory definitions
in un repository Dataform riflettano la struttura delle sottodirectory.
Nella sottodirectory sources, i nomi file devono fare riferimento all'origine
a cui il file è correlato. Aggiungi il nome dell'origine come prefisso ai nomi dei file, ad esempio analytics_filtered.sqlx
Nella sottodirectory intermediate, i nomi file devono identificare la sottodirectory,
in modo che i collaboratori possano distinguere chiaramente i file intermediate.
Seleziona un prefisso univoco e applicalo solo ai file nella directory intermediate. Ad esempio: stg_ads_concept.sqlx.
Nella sottodirectory outputs, i nomi file devono essere concisi, ad esempio orders.sqlx. Se hai tabelle outputs con gli stessi nomi in diverse sottodirectory di entità, aggiungi un prefisso che identifichi l'entità, ad esempio sales_revenue.sqlx e ads_revenue.sqlx.
L'esempio seguente mostra una struttura di sottodirectory all'interno della directory definitions con nomi di file conformi alla strategia di denominazione consigliata:
definitions/
sources/
google_analytics.sqlx
google_analytics_filtered.sqlx
intermediate/
stg_analytics_concept.sqlx
outputs/
customers.sqlx
sales/
sales.sqlx
sales_revenue.sqlx
ads/
campaigns.sqlx
ads_revenue.sqlx
Passaggi successivi
- Per scoprire di più sui flussi di lavoro SQL in Dataform, consulta Introduzione ai flussi di lavoro SQL.
- Per scoprire di più sui repository Dataform, consulta Creare un repository.
- Per scoprire di più sulla suddivisione dei repository, consulta Introduzione alla suddivisione dei repository.