Como estruturar o código em um repositório

Este documento descreve as práticas recomendadas para estruturar e nomear arquivos de fluxo de trabalho SQL no diretório definitions raiz de um repositório do Dataform. A estrutura recomendada do diretório definitions reflete as etapas de um fluxo de trabalho SQL. Você pode adotar qualquer estrutura que se adeque às necessidades da sua empresa.

Talvez você queira estruturar o código do fluxo de trabalho SQL no diretório definitions pelos seguintes motivos:

  • Melhorar a colaboração na base de código designando equipes para partes selecionadas do fluxo de trabalho.
  • Melhorar a manutenção do fluxo de trabalho do SQL em caso de mudanças organizacionais.
  • Melhorar a navegação pela base de código.
  • Melhorar a escalabilidade da base de código.
  • Minimizar a sobrecarga administrativa da sua equipe.

O diretório definitions raiz em um repositório do Dataform contém o código que cria elementos do fluxo de trabalho SQL. É possível organizar arquivos no diretório definitions em uma estrutura de diretórios que reflita a estrutura do fluxo de trabalho.

Ao desenvolver um fluxo de trabalho SQL, você declara tabelas de origem e as transforma para criar tabelas de saída que podem ser usadas para fins comerciais ou analíticos.

É possível distinguir três etapas principais de um fluxo de trabalho do SQL:

  1. Declaração de fontes de dados
  2. Transformação dos dados de origem
  3. Definição das tabelas de saída com base nos dados de origem transformados

A estrutura de subdiretórios a seguir no diretório definitions reflete as principais etapas de um fluxo de trabalho SQL:

sources
Declarações de fontes de dados e transformação básica dos dados de origem, por exemplo, filtragem.
intermediate
Tabelas e ações que leem de sources e transformam dados antes de usar os dados transformados para definir tabelas outputs. As tabelas geralmente não são expostas a outros processos ou ferramentas, como ferramentas de business intelligence (BI), depois que o Dataform as executa no BigQuery.
outputs
Definições de tabelas consumidas por processos ou ferramentas, como BI, depois que o Dataform as executa no BigQuery.
extra
Arquivos fora do pipeline principal do fluxo de trabalho do SQL, por exemplo, arquivos que contêm dados de fluxo de trabalho preparados para uso adicional, como machine learning. Um subdiretório opcional e personalizado.

Práticas recomendadas para sources

O subdiretório sources contém a primeira etapa do fluxo de trabalho SQL: declaração e transformação básica dos dados de origem.

No subdiretório sources, armazene declarações e tabelas de origem de dados que filtram, categorizam, convertem ou renomeiam colunas.

Evite armazenar tabelas que combinem dados de várias fontes.

Transforme dados sources em tabelas armazenadas no subdiretório intermediate.

Se você declarar fontes de dados de vários pools, por exemplo, do Google Ads ou do Google Analytics, dedique um subdiretório a cada um deles.

O exemplo a seguir mostra uma estrutura de subdiretório de sources com dois pools de origem:

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 você declarar várias tabelas de origem de dados no mesmo esquema, é possível consolidar as declarações em um único arquivo JavaScript. a Para mais informações sobre como criar declarações de origem de dados com JavaScript, consulte Criar fluxos de trabalho do Dataform com JavaScript.

O exemplo de código a seguir mostra várias fontes de dados em um esquema, declaradas em um único arquivo JavaScript:

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

Para proteger seu fluxo de trabalho SQL contra mudanças na fonte de dados, crie uma visualização para cada declaração de fonte de dados, por exemplo, analytics_users_filtered.sqlx. A visualização pode conter filtragem e formatação básica dos dados de origem. Armazene as visualizações no subdiretório sources.

Em seguida, ao criar tabelas intermediate ou outputs, consulte as visualizações em vez de tabelas de origem brutas. Essa abordagem permite testar as tabelas de origem. Caso uma tabela de origem mude, você pode modificar a visualização dela, por exemplo, adicionando filtros ou reformulando dados.

Práticas recomendadas para intermediate

O subdiretório intermediate contém a segunda etapa do fluxo de trabalho do SQL: transformação e agregação de dados de uma ou várias origens.

No subdiretório intermediate, armazene arquivos que transformam significativamente os dados de uma ou várias origens no subdiretório sources, por exemplo, tabelas que unem dados. As tabelas no subdiretório intermediate normalmente consultam dados de tabelas de origem ou de outras tabelas intermediate.

Use tabelas intermediate para criar tabelas outputs. Normalmente, as tabelas intermediate não são usadas para outros fins, como a análise de dados, depois que o Dataform as executa no BigQuery. Você pode pensar nas tabelas intermediate como a lógica de transformação de dados que permite a criação de tabelas de saída.

Recomendamos que você documente e teste todas as tabelas intermediate.

Práticas recomendadas para outputs

O subdiretório outputs contém a fase final do fluxo de trabalho do SQL: criação de tabelas de saída para fins comerciais com base em dados transformados.

No diretório outputs, armazene tabelas que você planeja usar em outros processos ou ferramentas depois que o Dataform as executar no BigQuery, por exemplo, relatórios ou painéis. As tabelas no diretório outputs geralmente consultam dados de tabelas intermediate.

Agrupe as tabelas outputs pela entidade de negócios a que elas estão relacionadas, por exemplo, marketing, pedidos ou análises. Dedique um subdiretório a cada entidade comercial.

Para armazenar tabelas de saída separadamente no BigQuery, configure um esquema dedicado para elas. Para instruções sobre como configurar o esquema de tabela, consulte Configurar outras configurações de tabela.

O exemplo a seguir mostra uma estrutura de subdiretório de outputs com entidades de negócios sales e marketing:

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

Recomendamos que você documente e teste todas as tabelas outputs.

Estratégia de nomenclatura

Os nomes de todos os arquivos no Dataform precisam estar em conformidade com as diretrizes de nomenclatura de tabelas do BigQuery.

Recomendamos que os nomes dos arquivos no diretório definitions em um repositório do Dataform reflitam a estrutura de subdiretórios.

No subdiretório sources, os nomes de arquivo precisam apontar para a origem com que o arquivo está relacionado. Adicione o nome da origem como um prefixo aos nomes de arquivos, por exemplo, analytics_filtered.sqlx

No subdiretório intermediate, os nomes de arquivo precisam identificar o subdiretório, para que os colaboradores possam distinguir claramente os arquivos intermediate. Selecione um prefixo exclusivo e aplique-o apenas a arquivos no diretório intermediate. Por exemplo, stg_ads_concept.sqlx.

No subdiretório outputs, os nomes de arquivos precisam ser concisos, por exemplo, orders.sqlx. Se você tiver tabelas outputs com os mesmos nomes em diferentes subdiretórios de entidades, adicione um prefixo que identifique a entidade, por exemplo, sales_revenue.sqlx e ads_revenue.sqlx.

O exemplo a seguir mostra uma estrutura de subdiretórios dentro do diretório definitions com nomes de arquivos que estão em conformidade com a estratégia de nomenclatura recomendada:

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

A seguir