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 delle API sulle risorse di compilazione. Un repository di grandi dimensioni può causare il superamento di queste quote e limiti. Ciò può comportare la mancata compilazione ed esecuzione del flusso di lavoro.

Per ridurre questo rischio, ti consigliamo di dividere i repository di grandi dimensioni. Quando dividi un repository di grandi dimensioni, suddividi un flusso di lavoro di grandi dimensioni in una serie di flussi di lavoro 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 dei repository suddivisi può essere più difficile rispetto alla gestione di un singolo repository.

Per scoprire di più sull'impatto delle dimensioni del repository in Dataform, vedi Panoramica delle dimensioni del repository. Per saperne 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 che riflettano le fasi del tuo flusso di lavoro. Tieni presente che puoi adottare una struttura personalizzata che soddisfi al meglio le tue esigenze.

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

  • sources per l'archiviazione delle dichiarazioni delle origini dati.
  • intermediate per archiviare la logica di trasformazione dei dati.
  • output per l'archiviazione delle 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 delle tabelle BigQuery. Ti consigliamo che i nomi dei file nella directory definitions di un repository Dataform riflettano la struttura delle sottodirectory.

Per scoprire di più sulle best practice per la strutturazione e la denominazione dei file in un repository, vedi Strutturare il codice in un repository.

Best practice per il ciclo di vita del codice

Il ciclo di vita del codice predefinito 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 unico repository Dataform con override di compilazione del workspace e configurazioni di release.

Puoi creare ambienti di esecuzione isolati nei seguenti modi:

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

Poi, puoi pianificare le esecuzioni negli ambienti di staging e produzione con le configurazioni del workflow. Ti consigliamo di attivare le esecuzioni manualmente nell'ambiente di sviluppo.

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

Ciclo di vita del codice in più repository

Per personalizzare le autorizzazioni 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.

Con questo approccio, ti consigliamo di mantenere la base di codice del repository uguale 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 del workflow.

Panoramica delle dimensioni del repository

Questa sezione ti aiuta a capire in che modo le dimensioni del repository influiscono sullo sviluppo del flusso di lavoro e sull'utilizzo delle risorse di compilazione di Dataform e come stimare l'utilizzo delle risorse di compilazione del 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 flusso di lavoro in un singolo repository può rendere difficile la navigazione nel repository.

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

  • Compilazione del flusso di lavoro. Dataform applica limiti di utilizzo alle risorse di compilazione. Un repository di grandi dimensioni può portare al superamento di questi limiti, causando l'errore di compilazione.

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

Se le grandi dimensioni del repository influiscono negativamente sullo sviluppo in Dataform, puoi dividere 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 workspace per generare una rappresentazione del workflow nel repository. Questo risultato viene chiamato risultato di compilazione. Dataform applica limiti di utilizzo alle risorse di compilazione.

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

  • Un bug di ciclo infinito nel codice del repository.
  • Un bug di perdita di memoria nel codice del repository.
  • Un repository di grandi dimensioni, con più di 1000 azioni del flusso di lavoro.

Per ulteriori informazioni sui limiti di utilizzo delle risorse di compilazione, consulta Limiti delle risorse di compilazione di Dataform.

Stimare l'utilizzo delle risorse di compilazione del repository

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

  • Utilizzo del tempo della CPU.
  • Dimensione totale massima dei dati serializzati del grafico delle azioni generato definito nel tuo repository.

Per ottenere un'approssimazione approssimativa dell'utilizzo attuale del tempo di CPU di compilazione per la compilazione del repository, puoi misurare il tempo di compilazione del flusso di lavoro Dataform su una macchina Linux o macOS locale.

  • Per misurare il tempo di compilazione del flusso di lavoro, all'interno del repository esegui il comando Dataform CLI dataform compile 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 della CPU per la compilazione del repository.

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

  • Per scrivere l'output del grafico compilato del flusso di lavoro in un file JSON, nel repository, esegui il seguente comando Dataform CLI:

    dataform compile --json > graph.json

Divisione dei repository

Questa sezione illustra le strategie per dividere un repository Dataform e gestire le 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 pacchetti e i file di configurazione Dataform. Puoi archiviare un flusso di lavoro in un unico repository o suddividerlo tra più repository.

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

  • Rispetto dei limiti di Dataform per l'utilizzo delle risorse di compilazione. La suddivisione di un flusso di lavoro di grandi dimensioni in più repository più piccoli riduce il rischio di superare i limiti di Dataform per le risorse di compilazione.
  • Processi di definizione granulare. Puoi impostare processi, ad esempio regole di integrazione continua (CI), individualmente per ogni frammento suddiviso del workflow e per il team che lo sviluppa.
  • Autorizzazioni granulari. Puoi impostare le autorizzazioni singolarmente per ogni frammento del flusso di lavoro e per il team che lo sviluppa per migliorare la sicurezza generale del flusso di lavoro.
  • Migliorare la collaborazione riducendo al minimo il numero di collaboratori che lavorano su ogni frammento suddiviso del flusso di lavoro.
  • Migliorare la leggibilità del codebase. La suddivisione dei file che compongono un flusso di lavoro di grandi dimensioni in più repository semplifica la navigazione in ogni repository individualmente rispetto alla navigazione nell'intero flusso di lavoro contemporaneamente.
  • Accelerando l'esecuzione del flusso di lavoro di ogni frammento suddiviso del flusso di lavoro rispetto all'esecuzione dell'intero flusso di lavoro.

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.
  • È necessaria una configurazione di pianificazione personalizzata per ogni repository Dataform e per il repository Git corrispondente.
  • Difficoltà nella gestione delle dipendenze tra gli oggetti del flusso di lavoro 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 flusso di lavoro completo.

Strategie per dividere un repository

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

Puoi scegliere di dividere 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 ogni dominio che utilizza i contenuti del repository centrale come origini dati.

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

Gestione delle dipendenze tra repository

Il modo più efficiente per dividere 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 dividendo un repository in una successione di repository, in cui un repository dipende dal precedente ed è un'origine dati per il successivo. La successione dei repository e delle relative dipendenze deve riflettere al meglio la struttura del flusso di lavoro principale.

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

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 dividere 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 quest'ultimo come origine dati. Le dipendenze bidirezionali tra i repository complicano la pianificazione e l'esecuzione del flusso di lavoro principale, nonché i processi di sviluppo.

Strutturare il codice in un repository

Questa sezione descrive le best practice per strutturare e denominare i file del workflow nella directory principale definitions di un repository Dataform. La struttura consigliata della directory definitions riflette le fasi di un flusso di lavoro. Puoi adottare qualsiasi struttura adatta alle esigenze della tua attività.

Potresti voler strutturare il codice del flusso di lavoro nella directory definitions per i seguenti motivi:

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

La directory radice definitions in un repository Dataform contiene il codice che crea gli elementi del flusso di lavoro. Puoi organizzare i file nella directory definitions in una struttura di directory che rifletta la struttura del workflow.

Quando sviluppi un flusso di lavoro, 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:

  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 flusso di lavoro:

sources
Dichiarazioni delle origini dati e trasformazione di base dei dati di origine, ad esempio il filtraggio.
intermediate
Tabelle e azioni che leggono da sources e trasformano i dati prima di utilizzare i dati trasformati per definire le tabelle outputs. Le tabelle in genere non sono 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 BI, dopo che Dataform le esegue in BigQuery.
extra
File al di fuori della 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 e le tabelle delle origini dati che filtrano, classificano, convertono o ridenominano 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 origini dati di più pool, ad esempio Google Ads o Google Analytics, dedica una sottodirectory a ogni pool.

Il seguente esempio 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 dell'origine dati all'interno dello 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 Creare flussi di lavoro esclusivamente 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 dalle modifiche all'origine dati, puoi creare una vista per ogni dichiarazione dell'origine dati, ad esempio analytics_users_filtered.sqlx. La visualizzazione può contenere il filtraggio e la formattazione di base dei dati di origine. Memorizza le visualizzazioni nella sottodirectory sources.

Poi, quando crei tabelle intermediate o outputs, fai riferimento alle visualizzazioni 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 visualizzazione, ad esempio aggiungendo filtri o eseguendo il recast dei 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, memorizza 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 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: la creazione di tabelle di output per i tuoi scopi aziendali a partire dai dati trasformati.

Nella directory outputs, archivia le tabelle che prevedi di utilizzare in processi o strumenti aggiuntivi dopo che Dataform le esegue 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 sulla configurazione dello schema della tabella, vedi Ignorare le impostazioni della tabella.

Il seguente esempio mostra una struttura di sottodirectory di outputs con le entità commerciali 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 delle tabelle BigQuery.

Ti consigliamo di fare in modo che i nomi dei file nella directory definitions in un repository Dataform riflettano la struttura delle sottodirectory.

Nella sottodirectory sources, i nomi file devono puntare all'origine a cui è correlato il file. Aggiungi il nome della fonte 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 outputs tabelle con lo stesso nome in diverse sottodirectory delle entità, 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 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