Best practice per i repository

Questo documento presenta le seguenti informazioni sui repository Dataform:

Panoramica delle best practice per i repository in Dataform

Questa sezione presenta una panoramica delle best practice per la gestione delle dimensioni del repository, della struttura del repository e del ciclo di vita del codice in Dataform.

Best practice per le dimensioni del repository

Le dimensioni del repository influiscono su diversi aspetti dello sviluppo in Dataform, ad esempio:

  • Collaborazione
  • Leggibilità del codebase
  • Processi di sviluppo
  • Compilazione del workflow
  • Esecuzione workflow

Dataform applica quote e limiti dell'API alle risorse di compilazione. Un repository di grandi dimensioni può causare il superamento di queste quote e limiti. Ciò può causare la mancata compilazione e l'esecuzione del workflow.

Per mitigare questo rischio, ti consigliamo di suddividere i repository di grandi dimensioni. Quando suddividi un repository di grandi dimensioni, dividi un workflow di grandi dimensioni in una serie di workflow più piccoli ospitati in repository diversi e collegati da dipendenze tra repository.

Questo approccio ti consente di rispettare le quote e i limiti di Dataform, implementare processi e autorizzazioni granulari e migliorare la leggibilità e la collaborazione del codebase. Tuttavia, la gestione di repository suddivisi può essere più complessa rispetto alla gestione di un singolo repository.

Per scoprire di più sull'impatto delle dimensioni del repository in Dataform, consulta Panoramica delle dimensioni del repository. Per scoprire di più sulle best practice per la suddivisione dei repository, consulta Suddivisione dei repository.

Best practice per la struttura del repository

Ti consigliamo di strutturare i file nella directory definitions in modo da riflettere le fasi del tuo workflow. Tieni presente che puoi adottare una struttura personalizzata che si adatta meglio alle tue esigenze.

La seguente struttura consigliata delle sottodirectory definitions riflette le fasi chiave della maggior parte dei flussi di lavoro:

  • sources per archiviare le dichiarazioni delle origini dati.
  • intermediate per archiviare la logica di trasformazione dei dati.
  • output per archiviare le definizioni delle tabelle di output.
  • extras (facoltativo) per archiviare file aggiuntivi.

I nomi di tutti i file in Dataform devono essere conformi alle linee guida per l'assegnazione dei nomi alle tabelle BigQuery. Ti consigliamo di assegnare ai file nella directory definitions di un repository Dataform nomi che riflettano la struttura delle sottodirectory.

Per scoprire di più sulle best practice per la strutturazione e la denominazione dei file in un repository, consulta Strutturazione del codice in un repository.

Best practice per il ciclo di vita del codice

Il ciclo di vita predefinito del codice in Dataform è costituito dalle seguenti fasi:

Per gestire il ciclo di vita del codice in Dataform, puoi creare ambienti di esecuzione come sviluppo, gestione temporanea e produzione.

Per scoprire di più sul ciclo di vita del codice in Dataform, consulta Introduzione al ciclo di vita del codice in Dataform.

Puoi scegliere di conservare gli ambienti di esecuzione in un unico repository o in più repository.

Ambienti di esecuzione in un unico repository

Puoi creare ambienti di esecuzione isolati, come sviluppo, gestione temporanea e produzione, in un singolo repository Dataform con override di compilazione del workspace e configurazioni di release.

Puoi creare ambienti di esecuzione isolati nei seguenti modi:

  • Suddividi le tabelle di sviluppo e di produzione per schema.
  • Suddividi le tabelle di sviluppo e produzione per schema e progetto Google Cloud .
  • Suddividi le tabelle di sviluppo, gestione temporanea e produzione per progetto Google Cloud .

In seguito, puoi pianificare le esecuzioni negli ambienti di gestione temporanea e di produzione con le configurazioni dei workflow. Ti consigliamo di attivare le esecuzioni manualmente nell'ambiente di sviluppo.

Per scoprire di più sulle best practice per la gestione del ciclo di vita del workflow in Dataform, consulta Best practice per il ciclo di vita del workflow.

Ciclo di vita del codice in più repository

Per personalizzare le autorizzazioni di Identity and Access Management per ogni fase del ciclo di vita del codice, puoi creare più copie di un repository e archiviarle in progetti Google Cloud diversi.

Ogni progetto Google Cloud funge da ambiente di esecuzione che corrisponde a una fase del ciclo di vita del codice, ad esempio sviluppo e produzione.

In questo approccio, ti consigliamo di mantenere invariato il codebase del repository in tutti i progetti. Per personalizzare la compilazione e l'esecuzione in ogni copia del repository, utilizza gli override di compilazione del workspace, le configurazioni delle release e le configurazioni dei workflow.

Panoramica delle dimensioni del repository

Questa sezione ti aiuta a capire in che modo le dimensioni del repository influiscono sullo sviluppo del workflow e sull'utilizzo delle risorse di compilazione di Dataform, nonché a stimare l'utilizzo delle risorse di compilazione del tuo repository.

Informazioni sulle dimensioni del repository in Dataform

Le dimensioni di un repository influiscono sui seguenti aspetti dello sviluppo in Dataform:

  • Collaborazione. Più collaboratori che lavorano su un repository di grandi dimensioni possono creare un numero eccessivo di richieste di pull, aumentando il rischio di conflitti di unione.

  • Leggibilità del codebase. Un numero maggiore di file che compongono un workflow in un singolo repository può rendere difficile la navigazione nel repository.

  • Processi di sviluppo. Alcune aree di un workflow di grandi dimensioni in un singolo repository potrebbero richiedere autorizzazioni o processi personalizzati, come la pianificazione, diversi dalle autorizzazioni e dai processi applicati al resto del workflow. Un repository di grandi dimensioni rende difficile adattare i processi di sviluppo ad aree specifiche del flusso di lavoro.

  • Compilazione del workflow. Dataform applica limiti di utilizzo alle risorse di compilazione. Un repository di grandi dimensioni può comportare il superamento di questi limiti, causando l'errore della compilazione.

  • Esecuzione del workflow. Durante l'esecuzione, Dataform esegue il codice del repository all'interno del tuo workspace ed esegue il deployment degli asset in BigQuery. Più grande è il repository, più tempo impiega Dataform per eseguirlo.

Se le dimensioni elevate del repository influiscono negativamente sullo sviluppo in Dataform, puoi suddividere il repository in più repository più piccoli.

Informazioni sui limiti delle risorse di compilazione del repository

Durante lo sviluppo, Dataform compila tutto il codice del repository all'interno del tuo workspace per generare una rappresentazione del workflow nel repository. Questo è chiamato risultato della compilazione. Dataform applica limiti di utilizzo alle risorse di compilazione.

Il repository potrebbe superare i limiti di utilizzo per i seguenti motivi:

  • Un bug di loop infinito nel codice del repository.
  • Un bug di perdita di memoria nel codice del repository.
  • Un repository di grandi dimensioni, con circa più di 1000 azioni del workflow.

Per saperne di più sui limiti di utilizzo delle risorse di compilazione, consulta Limiti delle risorse di compilazione di Dataform.

Stima l'utilizzo delle risorse di compilazione del repository

Puoi stimare l'utilizzo delle seguenti risorse di compilazione per il tuo repository:

Per ottenere un'approssimazione approssimativa del tempo di compilazione attuale per la compilazione del repository, puoi cronometrare la compilazione del workflow di Dataform su una macchina Linux o macOS locale.

  • Per cronometrare la compilazione del workflow, all'interno del repository, esegui il comando dataform compile dell'interfaccia a riga di comando di Dataform nel seguente formato:

    time dataform compile

    Il seguente esempio di codice mostra un risultato dell'esecuzione del comando time dataform compile:

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

Puoi considerare il risultato real come un indicatore approssimativo dell'utilizzo del tempo totale di esecuzione e il risultato user come un indicatore approssimativo dell'utilizzo del tempo di CPU per la compilazione del repository.

Per ottenere un'approssimazione approssimativa della dimensione totale del grafico delle azioni generato nel tuo repository, puoi scrivere l'output del grafico in un file JSON. Puoi considerare le dimensioni del file JSON non compresso come un indicatore approssimativo delle dimensioni totali del grafico.

  • Per scrivere l'output del grafico compilato del tuo workflow in un file JSON, esegui questo comando dell'interfaccia a riga di comando di Dataform all'interno del repository:

    dataform compile --json > graph.json

Suddivisione dei repository

Questa sezione illustra le strategie per la suddivisione di un repository Dataform e la gestione delle dipendenze tra repository.

I repository sono le unità principali di Dataform. Un repository archivia tutti i file SQLX e JavaScript che compongono il workflow, nonché i file di configurazione e i pacchetti Dataform. Puoi archiviare un workflow in un singolo repository o suddividerlo tra più repository.

La suddivisione di un repository in Dataform offre i seguenti vantaggi:

  • Rispettare i limiti delle risorse di compilazione di Dataform. La suddivisione di un workflow di grandi dimensioni in più repository più piccoli riduce il rischio di superare i limiti di Dataform sulle risorse di compilazione.
  • Processi di ottimizzazione. Puoi impostare processi, come le regole di integrazione continua (CI), singolarmente per ogni frammento suddiviso del tuo workflow e per il team che lo sviluppa.
  • Autorizzazioni granulari. Puoi impostare le autorizzazioni singolarmente per ogni frammento suddiviso del tuo workflow e per il team che lo sviluppa, in modo da migliorare la sicurezza complessiva del workflow.
  • Migliorare la collaborazione riducendo al minimo il numero di collaboratori che lavorano su ogni frammento suddiviso del workflow.
  • Migliorare la leggibilità del codebase. La suddivisione dei file che compongono un workflow di grandi dimensioni in più repository semplifica la navigazione di ogni repository singolarmente rispetto alla navigazione dell'intero workflow contemporaneamente.
  • Accelerare l'esecuzione del workflow di ogni frammento suddiviso del workflow rispetto all'esecuzione dell'intero workflow.

La suddivisione di un repository in Dataform presenta i seguenti svantaggi:

  • Configurazione personalizzata di integrazione continua e sviluppo continuo (CI/CD) richiesta per ogni repository Dataform e il relativo repository Git.
  • È richiesta una configurazione di pianificazione personalizzata per ogni repository Dataform e il relativo repository Git corrispondente.
  • Difficoltà nella gestione delle dipendenze tra gli oggetti del workflow ospitati in più repository.
  • Mancanza di una visualizzazione completa del grafo diretto aciclico (DAG) del flusso di lavoro SQL suddiviso tra più repository. In ogni repository, il DAG generato rappresenta solo una parte del workflow completo.

Strategie per la suddivisione di un repository

Quando suddividi un repository, dividi i file che compongono un workflow SQL principale in workflow secondari più piccoli ospitati in repository Dataform separati.

Puoi scegliere di suddividere un repository in uno dei seguenti modi:

  • Un repository per team di sviluppo.
  • Un repository per dominio, ad esempio vendite, marketing o logistica.
  • Un repository centrale e un repository per dominio che utilizza i contenuti del repository centrale come origini dati.

Per ospitare il workflow principale in una piattaforma di hosting Git di terze parti, devi connettere singolarmente ciascuno dei repository separati contenenti i workflow secondari a un repository Git di terze parti dedicato.

Gestione delle dipendenze tra repository

Il modo più efficiente per suddividere un repository è dividere il workflow SQL principale in workflow secondari autonomi, creando repository indipendenti. Un repository indipendente non utilizza i contenuti di un altro repository come origine dati. Questo approccio non richiede la gestione delle dipendenze tra repository.

Quando non puoi evitare le dipendenze tra repository, puoi gestirle suddividendo un repository in una serie di repository, in cui un repository dipende dal suo predecessore ed è un'origine dati per il suo successore. La successione dei repository e delle relative dipendenze deve riflettere al meglio la struttura del workflow principale.

Puoi creare dipendenze tra i repository con le dichiarazioni delle origini dati di Dataform. Puoi dichiarare un tipo di tabella BigQuery da un repository Dataform diverso come origine dati nel repository in fase di modifica. Dopo aver dichiarato un'origine dati, puoi farvi riferimento come a qualsiasi altra azione del workflow di Dataform e utilizzarla per sviluppare il tuo workflow.

Quando pianifichi l'esecuzione di un flusso di lavoro suddiviso tra repository con dipendenze tra repository, devi eseguire i repository uno alla volta nell'ordine delle dipendenze tra repository.

Ti consigliamo di evitare di suddividere un repository in un gruppo di repository con dipendenze bidirezionali. Una dipendenza bidirezionale tra repository si verifica quando un repository è un'origine dati per un altro repository e utilizza anche quel repository come origine dati. Le dipendenze bidirezionali tra i repository complicano la pianificazione e l'esecuzione del workflow principale, nonché i processi di sviluppo.

Strutturazione del codice in un repository

Questa sezione descrive le best practice per la strutturazione e la denominazione dei file del workflow nella directory root definitions di un repository Dataform. La struttura consigliata della directory definitions riflette le fasi di un workflow. Puoi adottare qualsiasi struttura adatta alle tue esigenze aziendali.

Puoi strutturare il codice del workflow nella directory definitions per i seguenti motivi:

  • Migliorare la collaborazione sul codebase assegnando i team a parti selezionate del workflow.
  • Migliorare la manutenibilità del workflow in caso di modifiche organizzative.
  • Migliorare la navigazione nel codebase.
  • Miglioramento della scalabilità del codebase.
  • Ridurre al minimo l'overhead amministrativo per il tuo team.

La directory root definitions in un repository Dataform contiene il codice che crea gli elementi del tuo workflow. Puoi organizzare i file nella directory definitions in una struttura di directory che riflette la struttura del workflow.

Quando sviluppi un workflow, 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 workflow:

  1. Dichiarazione delle origini dati.
  2. Trasformazione dei dati di origine.
  3. Definizione delle tabelle di output dai dati di origine trasformati.

La seguente struttura di sottodirectory nella directory definitions riflette le fasi chiave di un workflow:

sources
Dichiarazioni delle origini dati e trasformazione di base dei dati di origine, ad esempio il filtro.
intermediate
Tabelle e azioni che leggono da sources e trasformano i dati prima di utilizzarli per definire le tabelle outputs. In genere, le tabelle non vengono esposte a processi o strumenti aggiuntivi, come gli strumenti di business intelligence (BI), dopo che Dataform le ha eseguite in BigQuery.
outputs
Definizioni di tabelle utilizzate da processi o strumenti, come la BI, dopo che Dataform le ha eseguite in BigQuery.
extra
File esterni alla pipeline principale del workflow, ad esempio file che contengono dati del workflow preparati per un utilizzo 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: la dichiarazione e la trasformazione di base dei dati di origine.

Nella sottodirectory sources, archivia le dichiarazioni delle origini dati e le tabelle che filtrano, categorizzano, eseguono il cast o rinominano le colonne.

Evita di archiviare tabelle che combinano dati provenienti da più origini.

Trasforma i dati sources in tabelle archiviate nella sottodirectory intermediate.

Se dichiari 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 nello stesso schema, puoi consolidare le dichiarazioni in un unico file JavaScript.

Per saperne di più sulla creazione di dichiarazioni di origini dati con JavaScript, consulta Crea flussi di lavoro esclusivamente 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 workflow dalle modifiche alle origini dati, puoi creare una vista per ogni dichiarazione dell'origine dati, ad esempio analytics_users_filtered.sqlx. La vista può contenere il filtro e la formattazione di base dei dati di origine. Archivia le visualizzazioni nella sottodirectory sources.

Poi, quando crei tabelle intermediate o outputs, fai riferimento alle viste anziché alle tabelle di origine non elaborate. Questo approccio ti consente di testare le tabelle di origine. Se una tabella di origine cambia, puoi modificarne la vista, ad esempio aggiungendo filtri o riformulando i dati.

Best practice per intermediate

La sottodirectory intermediate contiene la seconda fase del flusso di lavoro: 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 da una o più origini nella sottodirectory sources, ad esempio le tabelle che uniscono i dati. Le tabelle nella sottodirectory intermediate in genere 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 altri scopi, ad esempio l'analisi dei dati, dopo che Dataform le ha eseguite 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 workflow: la creazione di tabelle di output per i tuoi 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'organizzazione aziendale a cui sono correlate, ad esempio marketing, ordini o analisi. Dedica una sottodirectory a ogni organizzazione 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 Esegui l'override delle impostazioni della tabella.

L'esempio seguente mostra una struttura di sottodirectory di outputs con le organizzazioni 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 l'assegnazione dei nomi alle tabelle BigQuery.

Ti consigliamo di assegnare ai file nella directory definitions di un repository Dataform nomi che riflettano la struttura delle sottodirectory.

Nella sottodirectory sources, i nomi 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 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 outputs tabelle con gli stessi nomi in sottodirectory di entità diverse, aggiungi un prefisso che identifichi l'entità, ad esempio sales_revenue.sqlx o 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

Best practice per la compilazione e la pianificazione

Quando configuri le esecuzioni pianificate e i workflow di orchestrazione per il tuo repository, segui queste best practice per garantire una compilazione affidabile:

  • Utilizza le configurazioni della release per le esecuzioni di produzione pianificate: una configurazione della release compila il codice del repository in base a una pianificazione prevedibile e archivia il risultato della compilazione. Quando le pipeline di esecuzione della produzione vengono eseguite, lo fanno immediatamente in base a questo risultato salvato, senza avviare richieste di rete al repository Git remoto.
  • Limita la compilazione commitish alle attività di sviluppo e a bassa frequenza: la chiamata di CreateCompilationResult direttamente su un commitish Git, ad esempio un branch, un tag o un SHA di commit, richiede a Dataform di clonare il repository sulla rete a ogni chiamata. Evita di configurare cron job di produzione o DAG di orchestrazione per la compilazione ripetuta da un commitish Git a frequenze elevate.
  • Configura i nuovi tentativi automatici e scagliona le pianificazioni: se la tua architettura richiede la compilazione da un commitish Git in scheduler esterni, configura i nuovi tentativi automatici con backoff esponenziale e scagliona i timer cron simultanei. Per esempi dettagliati di codice di nuovo tentativo e passaggi per la risoluzione dei problemi, consulta Impossibile raggiungere il repository remoto.

Passaggi successivi