Como estruturar o código em um repositório

Neste documento, descrevemos as práticas recomendadas para estruturar e nomear arquivos de fluxo de trabalho SQL no diretório raiz definitions de um repositório do Dataform. A estrutura recomendada do diretório definitions reflete os estágios de um fluxo de trabalho SQL. Você pode adotar qualquer estrutura que atenda às necessidades do seu negócio.

É possível 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 SQL em caso de mudanças organizacionais.
  • Melhorar a navegação pela sua base de código.
  • Melhorando a escalonabilidade da base de código.
  • Minimizar a sobrecarga administrativa para sua equipe.

O diretório raiz definitions em um repositório do Dataform contém um código que cria elementos do fluxo de trabalho SQL. É possível organizar os 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 de análise.

É possível distinguir três estágios principais de um fluxo de trabalho SQL:

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

A estrutura de subdiretórios a seguir no diretório definitions reflete os principais estágios de um fluxo de trabalho SQL:

sources
Declarações e transformação básica da fonte de dados, 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. Geralmente, as tabelas não são expostas a outros processos ou ferramentas, como ferramentas de Business Intelligence (BI), depois que o Dataform executa essas tabelas 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 SQL, por exemplo, arquivos que contêm dados do fluxo de trabalho preparados para uso extra, como machine learning. Um subdiretório opcional e personalizado.

Práticas recomendadas para sources

O subdiretório sources contém o primeiro estágio do seu fluxo de trabalho SQL: declaração e transformação básica dos dados de origem.

No subdiretório sources, armazene as declarações da fonte de dados e tabelas que filtram, categorizam, transmitem ou renomeiam colunas.

Evite armazenar tabelas que combinem dados de fontes diferentes.

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

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

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 fonte de dados no mesmo esquema, poderá consolidar as declarações em um único arquivo JavaScript. Em um arquivo JavaScript, você pode armazenar várias declarações de fonte de dados. Para saber mais sobre como criar declarações de fonte de dados com JavaScript, consulte Criar fluxos de trabalho SQL 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 filtros básicos e formatação dos dados de origem. Armazene as visualizações no subdiretório sources.

Em seguida, ao criar tabelas intermediate ou outputs, faça referência às visualizações em vez das tabelas de origem brutas. Essa abordagem permite testar as tabelas de origem. Se uma tabela de origem mudar, você poderá modificar a visualização adicionando filtros ou refazendo a transmissão de dados, por exemplo.

Práticas recomendadas para intermediate

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

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

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

Recomendamos documentar e testar todas as tabelas intermediate.

Práticas recomendadas para outputs

O subdiretório outputs contém o estágio final do fluxo de trabalho SQL: criação de tabelas de saída para seus fins comerciais a partir de dados transformados.

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

Agrupe as tabelas outputs pela entidade comercial a que 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 tabelas de saída. Para instruções sobre como configurar o esquema da tabela, consulte Definir outras configurações da tabela.

O exemplo a seguir mostra uma estrutura de subdiretório de outputs com duas entidades comerciais:

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

Recomendamos documentar e testar 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 dos arquivos precisam apontar para a origem a 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 somente aos arquivos no diretório intermediate. Por exemplo, stg_ads_concept.sqlx.

No subdiretório outputs, os nomes dos arquivos precisam ser concisos, por exemplo, orders.sqlx. Se você tiver tabelas outputs com os mesmos nomes em subdiretórios de entidades diferentes, 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ório 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