Questo documento descrive le best practice per strutturare e assegnare un nome ai file di flusso di lavoro SQL nella directory radice definitions di un repository Dataform. La struttura consigliata della directory definitions riflette le fasi di un flusso di lavoro SQL. Puoi adottare qualsiasi struttura che si adatti alle tue esigenze aziendali.
Potresti voler strutturare il codice del flusso di lavoro SQL nella directory definitions per i seguenti motivi:
- Migliorando la collaborazione sul codebase designando i team in parti selezionate del flusso di lavoro.
- Migliorare la gestibilità del flusso di lavoro SQL in caso di cambiamenti dell'organizzazione.
- Miglioramento della navigazione nel codebase.
- Miglioramento della scalabilità del codebase.
- Ridurre al minimo l'overhead amministrativo per il tuo team.
Struttura consigliata della directory definitions
La directory radice definitions in un repository Dataform contiene codice che crea elementi del flusso di lavoro SQL. Puoi organizzare i file della directory definitions in una struttura di directory che riflette la struttura del flusso di lavoro.
Quando sviluppi un flusso di lavoro SQL, dichiari le tabelle di origine e le trasforma per creare tabelle di output che puoi utilizzare per scopi aziendali o di analisi.
Puoi distinguere tre fasi fondamentali 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 delle 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 l'applicazione di filtri.
intermediate- Tabelle e azioni che leggono da
sourcese trasformano i dati prima di utilizzare i dati trasformati per definire le tabelleoutputs. In genere, le tabelle non sono esposte a processi o strumenti aggiuntivi, come gli strumenti di business intelligence (BI), dopo che Dataform le esegue su 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 file che contengono 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, categorizzano, trasmettono o rinominano le colonne.
Evita di archiviare tabelle che combinano dati provenienti da più origini.
Trasforma i dati sources nelle tabelle archiviate nella sottodirectory intermediate.
Se dichiari le origini dati da più pool, ad esempio Google Ads o Google Analytics, dedica una sottodirectory a ogni pool.
L'esempio seguente mostra una struttura di sottodirectory di sources
con due pool di origine:
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 all'interno dello stesso schema, puoi consolidare le relative dichiarazioni in un unico file JavaScript. In un file JavaScript puoi archiviare più dichiarazioni delle origini dati. Per ulteriori informazioni sulla creazione di dichiarazioni delle origini dati con JavaScript, consulta Creare flussi di lavoro Dataform SQL con JavaScript.
Il seguente esempio di codice mostra più origini dati all'interno di uno schema, dichiarate in un singolo file JavaScript:
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
Per proteggere il tuo flusso di lavoro SQL dalle modifiche all'origine dati, puoi creare una vista per ogni dichiarazione dell'origine dati, ad esempio analytics_users_filtered.sqlx.
La vista può contenere filtri e formattazione di base dei dati di origine.
Archivia le visualizzazioni nella sottodirectory sources.
Quando crei le tabelle intermediate o outputs, fai quindi riferimento alle viste
anziché alle tabelle di origine non elaborate. Questo approccio consente di testare le tabelle di origine.
Se una tabella di origine viene modificata, puoi modificarne la visualizzazione, ad esempio aggiungendo filtri o ritrasmettendo i dati.
Best practice per intermediate
La sottodirectory intermediate contiene la seconda fase del flusso di lavoro SQL:
trasformazione e 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 da una o più origini nella sottodirectory sources, ad esempio le tabelle che uniscono i dati. In genere, le tabelle nella sottodirectory intermediate eseguono query sui dati delle tabelle di origine o di altre tabelle intermediate.
Utilizza le tabelle intermediate per creare le tabelle outputs.
In genere, le tabelle intermediate non vengono utilizzate per scopi aggiuntivi, ad esempio l'analisi dei dati, dopo che Dataform le ha eseguite su BigQuery.
Le tabelle intermediate possono essere considerate 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 scopi aziendali dai dati trasformati.
Nella directory outputs, archivia le tabelle che prevedi di utilizzare in altri processi o strumenti dopo che Dataform le ha eseguite in BigQuery, ad esempio report o dashboard. Le tabelle nella directory outputs in genere 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 istruzioni su come configurare lo schema della tabella, consulta Configurare impostazioni aggiuntive della tabella.
Il seguente esempio mostra una struttura di sottodirectory di outputs
con due entità aziendali:
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.
Consigliamo che i nomi dei file nella directory definitions in un repository Dataform riflettano la struttura della sottodirectory.
Nella sottodirectory sources, i nomi dei file devono puntare all'origine a cui è correlato il file. Aggiungi il nome dell'origine come prefisso ai nomi file, ad esempio analytics_filtered.sqlx
Nella sottodirectory intermediate, i nomi dei 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 dei file devono essere concisi,
ad esempio orders.sqlx. Se hai tabelle outputs con gli stessi nomi in
directory di entità diverse, 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 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 ulteriori informazioni sui repository Dataform, consulta Introduzione ai repository.
- Per saperne di più sulla suddivisione dei repository, consulta Introduzione alla suddivisione dei repository.