Práticas recomendadas para repositórios

Este documento apresenta as seguintes informações sobre os repositórios do Dataform:

Informações gerais sobre as práticas recomendadas de repositório no Dataform

Esta seção apresenta uma visão geral das práticas recomendadas para gerenciar o tamanho, a estrutura e o ciclo de vida do código do repositório no Dataform.

Práticas recomendadas para o tamanho do repositório

O tamanho do repositório afeta vários aspectos do desenvolvimento no Dataform, como os seguintes:

  • Colaboração
  • Legibilidade da base de código
  • Processos de desenvolvimento
  • Compilação do fluxo de trabalho
  • Execução do fluxo de trabalho

O Dataform aplica cotas e limites de API em recursos de compilação. Um repositório grande pode fazer com que ele exceda essas cotas e limites. Isso pode levar à falha na compilação e execução do seu fluxo de trabalho.

Para reduzir esse risco, recomendamos dividir repositórios grandes. Ao dividir um repositório grande, você divide um fluxo de trabalho grande em vários fluxos de trabalho menores armazenados em repositórios diferentes e conectados por dependências entre repositórios.

Essa abordagem permite aderir às cotas e aos limites do Dataform, implementar processos e permissões refinados e melhorar a legibilidade e a colaboração da base de código. No entanto, gerenciar repositórios divididos pode ser mais difícil do que gerenciar um único repositório.

Para saber mais sobre o impacto do tamanho do repositório no Dataform, consulte Visão geral do tamanho do repositório. Para saber mais sobre as práticas recomendadas para dividir repositórios, consulte Dividir repositórios.

Práticas recomendadas para a estrutura do repositório

Recomendamos estruturar os arquivos no diretório definitions para refletir os estágios do fluxo de trabalho. É possível adotar uma estrutura personalizada que melhor se adapte às suas necessidades.

A estrutura recomendada de subdiretórios definitions a seguir reflete as principais etapas da maioria dos fluxos de trabalho:

  • sources para armazenar declarações de origem de dados.
  • intermediate para armazenar a lógica de transformação de dados.
  • output para armazenar definições de tabelas de saída.
  • extras (opcional) para armazenar outros arquivos.

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.

Para saber mais sobre as práticas recomendadas para estruturar e nomear arquivos em um repositório, consulte Como estruturar código em um repositório.

Práticas recomendadas para o ciclo de vida do código

O ciclo de vida de código padrão no Dataform consiste nas seguintes fases:

Para gerenciar o ciclo de vida do código no Dataform, crie ambientes de execução, como desenvolvimento, preparação e produção.

Para saber mais sobre o ciclo de vida do código no Dataform, consulte Introdução ao ciclo de vida do código no Dataform.

Você pode manter seus ambientes de execução em um único repositório ou em vários.

Ambientes de execução em um único repositório

É possível criar ambientes de execução isolados, como desenvolvimento, preparação e produção, em um único repositório do Dataform com substituições de compilação do espaço de trabalho e configurações de versão.

É possível criar ambientes de execução isolados das seguintes maneiras:

  • Divida as tabelas de desenvolvimento e produção por esquema.
  • Divida as tabelas de desenvolvimento e produção por esquema e Google Cloud projeto.
  • Divida as tabelas de desenvolvimento, preparação e produção por Google Cloud projeto.

Depois, você pode programar execuções nos ambientes de teste e de produção com configurações de fluxo de trabalho. Recomendamos acionar as execuções manualmente no ambiente de desenvolvimento.

Para saber mais sobre as práticas recomendadas para gerenciar o ciclo de vida do código no Dataform, consulte Gerenciar o ciclo de vida do código.

Ciclo de vida do código em vários repositórios

Para personalizar permissões de gerenciamento de identidade e acesso em cada etapa do ciclo de vida do código, crie várias cópias de um repositório e armazene-as em diferentes projetos Google Cloud .

Cada Google Cloud projeto serve como um ambiente de execução que corresponde a uma etapa do ciclo de vida do código, por exemplo, desenvolvimento e produção.

Nessa abordagem, recomendamos manter a base de código do repositório igual em todos os projetos. Para personalizar a compilação e a execução em cada cópia do repositório, use substituições de compilação do espaço de trabalho, configurações de lançamento e configurações de fluxo de trabalho.

Visão geral do tamanho do repositório

Esta seção ajuda você a entender como o tamanho do repositório afeta o desenvolvimento do fluxo de trabalho e o uso de recursos de compilação do Dataform, além de como estimar o uso de recursos de compilação do repositório.

Sobre o tamanho do repositório no Dataform

O tamanho de um repositório afeta os seguintes aspectos do desenvolvimento no Dataform:

  • Colaboração. Vários colaboradores trabalhando em um repositório grande podem criar um número excessivo de solicitações de pull, aumentando o risco de conflitos de mesclagem.

  • Legibilidade da base de código. Um número maior de arquivos que compõem um fluxo de trabalho em um único repositório pode dificultar a navegação pelo repositório.

  • Processos de desenvolvimento. Algumas áreas de um fluxo de trabalho grande em um único repositório podem exigir permissões ou processos personalizados, como programação, diferentes das permissões e dos processos aplicados ao restante do fluxo de trabalho. Um repositório grande dificulta a adaptação dos processos de desenvolvimento a áreas específicas do fluxo de trabalho.

  • Compilação do fluxo de trabalho. O Dataform aplica limites de uso aos recursos de compilação. Um tamanho grande de repositório pode levar ao excesso desses limites, fazendo com que a compilação falhe.

  • Execução do fluxo de trabalho. Durante a execução, o Dataform executa o código do repositório no seu espaço de trabalho e implanta recursos no BigQuery. Quanto maior o repositório, mais tempo o Dataform leva para executá-lo.

Se o tamanho grande do repositório afetar negativamente o desenvolvimento no Dataform, você poderá dividir o repositório em vários repositórios menores.

Sobre os limites de recursos de compilação do repositório

Durante o desenvolvimento, o Dataform compila todo o código do repositório no seu espaço de trabalho para gerar uma representação do fluxo de trabalho no repositório. Isso é chamado de resultado da compilação. O Dataform aplica limites de uso aos recursos de compilação.

Seu repositório pode exceder os limites de uso pelos seguintes motivos:

  • Um bug de loop infinito no código do repositório.
  • Um bug de vazamento de memória no código do repositório.
  • Um repositório grande, com aproximadamente mais de 1.000 ações de fluxo de trabalho.

Para mais informações sobre os limites de uso de recursos de compilação, consulte Limites de recursos de compilação do Dataform.

Estimar o uso de recursos de compilação do repositório

É possível estimar o uso dos seguintes recursos de compilação para seu repositório:

  • Uso de tempo da CPU.
  • Tamanho total máximo de dados serializados do gráfico gerado de ações definidas no seu repositório.

Para ter uma aproximação aproximada do uso atual de tempo de CPU para a compilação do repositório, você pode cronometrar a compilação do fluxo de trabalho do Dataform em uma máquina local do Linux ou do macOS.

  • Para cronometrar a compilação do fluxo de trabalho, dentro do repositório, execute o comando dataform compile da CLI do Dataform no seguinte formato:

    time dataform compile

    O exemplo de código abaixo mostra o resultado da execução do comando time dataform compile:

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

É possível tratar o resultado real como um indicador aproximado do uso do tempo da CPU para a compilação do repositório.

Para ter uma aproximação aproximada do tamanho total do gráfico de ações gerado no repositório, grave a saída do gráfico em um arquivo JSON. Você pode tratar o tamanho do arquivo JSON descompactado como um indicador aproximado do tamanho total do gráfico.

  • Para gravar a saída do gráfico compilado do seu fluxo de trabalho em um arquivo JSON, dentro do repositório, execute o seguinte comando da CLI do Dataform:

    dataform compile --json > graph.json

Como dividir repositórios

Esta seção discute estratégias para dividir um repositório do Dataform e gerenciar dependências entre repositórios.

Os repositórios são as unidades principais do Dataform. Um repositório armazena todos os arquivos SQLX e JavaScript que compõem seu fluxo de trabalho, bem como os arquivos e pacotes de configuração do Dataform. É possível armazenar um fluxo de trabalho em um único repositório ou dividir um fluxo de trabalho entre vários repositórios.

A divisão de um repositório no Dataform traz as seguintes vantagens:

  • Siga os limites do Dataform para o uso de recursos de compilação. A divisão de um fluxo de trabalho grande em vários repositórios menores reduz o risco de exceder os limites do Dataform nos recursos de compilação.
  • Detalhamento de processos. É possível definir processos, como regras de integração contínua (CI), individualmente para cada fragmento dividido do fluxo de trabalho e para a equipe que o desenvolve.
  • Permissões detalhadas. É possível definir permissões individualmente para cada fragmento dividido do fluxo de trabalho e para a equipe que o desenvolve para melhorar a segurança geral do fluxo de trabalho.
  • Melhorar a colaboração minimizando o número de colaboradores que trabalham em cada fragmento dividido do seu fluxo de trabalho.
  • Melhoramos a legibilidade da base de código. A divisão dos arquivos que compõem um grande fluxo de trabalho em vários repositórios facilita a navegação em cada repositório individualmente, em vez de navegar por todo o fluxo de trabalho de uma só vez.
  • Acelerar a execução do fluxo de trabalho de cada fragmento dividido do fluxo de trabalho em comparação com a execução de todo o fluxo de trabalho.

A divisão de um repositório no Dataform tem as seguintes desvantagens:

  • Configuração personalizada de integração e desenvolvimento contínuos (CI/CD) necessária para cada repositório do Dataform e o repositório do Git correspondente.
  • Configuração de programação personalizada necessária para cada repositório do Dataform e o repositório Git correspondente.
  • Dificuldade em gerenciar dependências entre os objetos do seu fluxo de trabalho armazenados em vários repositórios.
  • Falta de visualização abrangente do gráfico acíclico dirigido (DAG) do fluxo de trabalho SQL dividido entre vários repositórios. Em cada repositório, o DAG gerado representa apenas uma parte do fluxo de trabalho completo.

Estratégias para dividir um repositório

Ao dividir um repositório, você divide os arquivos que compõem um fluxo de trabalho SQL pai em fluxos de trabalho filhos menores armazenados em repositórios do Dataform separados.

Você pode dividir um repositório de uma das seguintes maneiras:

  • Um repositório por equipe de desenvolvimento.
  • Um repositório por domínio, por exemplo, vendas, marketing ou logística.
  • Um repositório central e um repositório por domínio que usa o conteúdo do repositório central como fontes de dados.

Para armazenar o fluxo de trabalho pai em uma plataforma de hospedagem de Git de terceiros, é necessário conectar individualmente cada um dos repositórios separados que contêm fluxos de trabalho filhos a um repositório Git de terceiros dedicado.

Gerenciar dependências entre repositórios

A maneira mais eficiente de dividir um repositório é dividir o fluxo de trabalho SQL pai em fluxos de trabalho filhos independentes, criando repositórios independentes. Um repositório independente não usa o conteúdo de um repositório diferente como fonte de dados. Essa abordagem não exige o gerenciamento de dependências entre repositórios.

Quando não for possível evitar dependências entre repositórios, é possível gerenciá-las dividindo um repositório em uma sucessão de repositórios, em que um repositório depende do antecessor e é uma fonte de dados para o sucessor. A sucessão de repositórios e as dependências deles precisam refletir melhor a estrutura do fluxo de trabalho principal.

É possível criar dependências entre repositórios com declarações de fonte de dados do Dataform. É possível declarar um tipo de tabela do BigQuery de um repositório diferente do Dataform como uma fonte de dados no repositório que está sendo editado. Depois de declarar uma fonte de dados, é possível fazer referência a ela como qualquer outra ação de fluxo de trabalho do Dataform e usá-la para desenvolver seu fluxo de trabalho.

Ao programar a execução de uma divisão de fluxo de trabalho entre repositórios com dependências entre repositórios, é necessário executar os repositórios um por um na ordem das dependências entre repositórios.

Recomendamos evitar dividir um repositório em um grupo de repositórios com dependências de duas vias. Uma dependência bidirecional entre repositórios ocorre quando um repositório é uma fonte de dados para outro repositório e também usa esse repositório como uma fonte de dados. As dependências bidirecionais entre repositórios complicam a programação e a execução do fluxo de trabalho pai, além dos processos de desenvolvimento.

Como estruturar o código em um repositório

Esta seção descreve as práticas recomendadas para estruturar e nomear arquivos de fluxo de trabalho 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. Você pode adotar qualquer estrutura que se adapte às necessidades da sua empresa.

Talvez você queira estruturar o código do fluxo de trabalho 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 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 raiz definitions em um repositório do Dataform contém o código que cria elementos do seu fluxo de trabalho. É 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, 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.

Você pode distinguir três etapas principais de um fluxo de trabalho:

  1. Declaração das fontes de dados.
  2. Transformação de dados de origem.
  3. Definição de 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:

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 seu fluxo de trabalho, 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: a declaração e a 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, poderá consolidar as declarações em um único arquivo JavaScript.

Para mais informações sobre como criar declarações de fonte 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 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 a 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: a transformação e agregação dos 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 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 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: a criação de tabelas de saída para fins comerciais com base nos 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 das tabelas intermediate.

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

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 arquivo, 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 aos arquivos no diretório intermediate, por exemplo, stg_ads_concept.sqlx.

No subdiretório outputs, os nomes de arquivo 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 ou 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