Este documento apresenta as seguintes informações sobre os repositórios do Dataform:
- Visão geral das práticas recomendadas para repositórios no Dataform
- Visão geral do tamanho do repositório
- Como dividir repositórios
- Como estruturar o código em um repositório
- Práticas recomendadas para compilação e programação
Visão geral das práticas recomendadas para repositórios no Dataform
Nesta seção, apresentamos uma visão geral das práticas recomendadas para gerenciar o tamanho do repositório, a estrutura do repositório e o ciclo de vida do código 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 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, alojados em repositórios diferentes e conectados por dependências entre repositórios.
Essa abordagem permite que você siga as cotas e os limites do Dataform, implemente processos e permissões refinados e melhore a legibilidade e a colaboração da base de código. No entanto, gerenciar repositórios divididos pode ser mais desafiador 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 Como dividir repositórios.
Práticas recomendadas para a estrutura do repositório
Recomendamos estruturar os arquivos no diretório definitions para refletir as
etapas do fluxo de trabalho. Lembre-se de que é 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:
sourcespara armazenar declarações de fonte de dados.intermediatepara armazenar a lógica de transformação de dados.outputpara 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 tabela do BigQuery. Recomendamos que os nomes dos arquivos
no diretório definitions em um repositório do Dataform reflitam
a estrutura do subdiretório.
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 do código padrão no Dataform consiste nas seguintes fases:
Desenvolvimento de código de fluxo de trabalho em espaços de trabalho do Dataform.
É possível desenvolver com o Dataform Core ou exclusivamente com JavaScript.
Compilação do código em um resultado de compilação usando as configurações do arquivo de configurações do fluxo de trabalho.
É possível configurar resultados de compilação personalizados com configurações de lançamento e substituições de compilação do espaço de trabalho.
Com as configurações de lançamento, é possível configurar resultados de compilação personalizados de todo o repositório. Depois, é possível programar a execução deles em configurações de fluxo de trabalho.
Com as substituições de compilação do espaço de trabalho, é possível configurar substituições de compilação para todos os espaços de trabalho no seu repositório, criando resultados de compilação personalizados de cada espaço de trabalho.
Execução do resultado da compilação no BigQuery.
É possível programar execuções ou resultados de compilação de repositórios com configurações de fluxo de trabalho.
Para gerenciar o ciclo de vida do código no Dataform, crie ambientes de execução, como desenvolvimento, preparo 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.
É possível manter os 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, preparo 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 lançamento.
É possível criar ambientes de execução isolados das seguintes maneiras:
- Dividir as tabelas de desenvolvimento e produção por esquema.
- Dividir as tabelas de desenvolvimento e produção por esquema e projeto do Google Cloud .
- Divida as tabelas de desenvolvimento, preparo e produção por projeto do Google Cloud .
Em seguida, é possível programar execuções em ambientes de preparo e 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 fluxo de trabalho no Dataform, consulte Práticas recomendadas para o ciclo de vida do fluxo de trabalho.
Ciclo de vida do código em vários repositórios
Para adaptar as permissões do Identity and Access Management a cada estágio do ciclo de vida do código, crie várias cópias de um repositório e armazene-as em diferentes projetos do Google Cloud .
Cada projeto do Google Cloud serve como um ambiente de execução que corresponde a um estágio 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
Nesta seção, você vai 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 seu 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 por ele.
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, que sã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 repositório grande pode exceder esses 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 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, divida 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 de 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 mais de 1.000 ações de fluxo de trabalho.
Para mais informações sobre limites de uso em 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 do tempo de CPU.
- Uso do tempo decorrido.
- Tamanho máximo total de dados serializados do gráfico de ações gerado definido no repositório.
Para ter uma aproximação do tempo de compilação atual do repositório, cronometre a compilação do fluxo de trabalho do Dataform em uma máquina local Linux ou macOS.
Para cronometrar a compilação do fluxo de trabalho, dentro do repositório, execute o comando
dataform compileda CLI do Dataform no seguinte formato:time dataform compileO exemplo de código a seguir mostra o resultado da execução do comando
time dataform compile:real 0m3.480s user 0m1.828s sys 0m0.260s
O resultado de real pode ser tratado como um indicador aproximado do uso do tempo decorrido, e o resultado de user como um indicador aproximado do uso do tempo de CPU para
a compilação do repositório.
Para ter uma aproximação do tamanho total do gráfico de ações gerado no repositório, grave a saída do gráfico em um arquivo JSON. O tamanho do arquivo JSON descompactado pode ser considerado um indicador aproximado do tamanho total do gráfico.
Para gravar a saída do gráfico compilado do fluxo de trabalho em um arquivo JSON, no repositório, execute o seguinte comando da CLI do Dataform:
dataform compile --json > graph.json
Como dividir repositórios
Nesta seção, discutimos 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, além dos arquivos e pacotes de configuração do Dataform. É possível armazenar um fluxo de trabalho em um único repositório ou dividi-lo entre vários repositórios.
Dividir um repositório no Dataform tem as seguintes vantagens:
- Seguir os limites de recursos de compilação do Dataform. Dividir um fluxo de trabalho grande em vários repositórios menores reduz o risco de exceder os limites do Dataform em recursos de compilação.
- Processos de refinamento. É 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 granulares. É possível definir permissões individualmente para cada fragmento dividido do fluxo de trabalho e para a equipe que o desenvolve, aumentando 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 fluxo de trabalho.
- Melhorar a legibilidade da base de código. Dividir os arquivos que compõem um fluxo de trabalho grande 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.
Dividir um repositório no Dataform tem as seguintes desvantagens:
- Configuração personalizada de integração contínua e desenvolvimento contínuo (CI/CD) necessária para cada repositório do Dataform e o repositório 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 fluxo de trabalho alojados 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, alojados em repositórios separados do Dataform.
É possível 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 hospedar o fluxo de trabalho pai em uma plataforma de hospedagem 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.
Como 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, gerencie-as dividindo um repositório em uma sucessão de repositórios, em que um repositório depende do predecessor 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 pai.
É 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 referenciá-la 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 um fluxo de trabalho dividido 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 a divisão de um repositório em um grupo de repositórios com dependências bidirecionais. 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 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
Nesta seção, descrevemos as práticas recomendadas para estruturar e nomear arquivos de fluxo de trabalho no diretório raiz definitions 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 atenda à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 capacidade de manutenção do fluxo de trabalho em caso de mudanças organizacionais.
- Melhorar a navegação pela base de código.
- Melhorar a escalonabilidade da base de código.
- Minimizar o overhead administrativo da sua equipe.
Estrutura recomendada do diretório definitions
O diretório raiz definitions em um repositório do Dataform
contém o código que cria elementos do fluxo de trabalho. É 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, 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:
- Declaração de fontes de dados.
- Transformação de dados de origem.
- Definição de tabelas de saída dos 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 fonte de dados e transformação básica de dados de origem, como filtragem.
intermediate- Tabelas e ações que leem de
sourcese transformam dados antes de você usar os dados transformados para definir tabelasoutputs. As tabelas normalmente 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, como 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 o primeiro estágio do fluxo de trabalho:
a declaração e a transformação básica dos dados de origem.
No subdiretório sources, armazene declarações de fonte de dados e tabelas
que filtram, categorizam, convertem ou renomeiam colunas.
Evite armazenar tabelas que combinam dados de várias fontes.
Transforme os dados de sources em tabelas armazenadas no subdiretório intermediate.
Se você declarar fontes de dados de vários pools, como o Google Ads ou o 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.
Para mais informações sobre como criar declarações de fonte de dados com JavaScript, consulte Criar fluxos de trabalho exclusivamente 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 a formatação básicas 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 de tabelas de origem brutas. Essa abordagem permite testar as tabelas de origem.
Se uma tabela de origem mudar, você poderá modificar a visualização dela, por exemplo,
adicionando filtros ou reformulando dados.
Práticas recomendadas para intermediate
O subdiretório intermediate contém o segundo estágio do fluxo de trabalho:
a transformação e a agregação dos 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 fontes no subdiretório sources, por exemplo, tabelas que mesclam 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 outras finalidades, como análise de dados, depois que
o Dataform as executa no BigQuery. Pense nas tabelas do 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 o estágio 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 as tabelas que você planeja usar em outros
processos ou ferramentas depois que o Dataform as executar no
BigQuery, como relatórios ou painéis. As tabelas no diretório outputs normalmente consultam dados das tabelas intermediate.
Agrupe as tabelas do outputs pela entidade empresarial relacionada, por exemplo, marketing, pedidos ou análise. Dedique um subdiretório a cada entidade
empresarial.
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 Substituir configurações de tabela.
O exemplo a seguir mostra uma estrutura de subdiretório de outputs
com as entidades empresariais 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 do subdiretório.
No subdiretório sources, os nomes de arquivo precisam apontar para a origem
relacionada ao arquivo. 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
subdiretórios de entidades diferentes, 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ório dentro do diretório definitions
com nomes de arquivo 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
Práticas recomendadas para compilação e programação
Ao configurar execuções programadas e fluxos de trabalho de orquestração para seu repositório, siga estas práticas recomendadas para garantir uma compilação confiável:
- Use configurações de lançamento para execuções de produção programadas: uma configuração de lançamento compila o código do repositório em uma programação previsível e armazena o resultado da compilação. Quando os pipelines de execução de produção são executados, eles são executados imediatamente com base nesse resultado salvo, sem iniciar solicitações de rede para o repositório Git remoto.
- Limite a compilação de commitish a tarefas de desenvolvimento e de baixa frequência: chamar
CreateCompilationResultdiretamente em um commitish do Git, como uma ramificação, tag ou SHA de commit, exige que o Dataform clone o repositório pela rede em cada invocação. Evite configurar cron jobs de produção ou DAGs de orquestração para compilar repetidamente de um commitish do Git em alta frequência. - Configure novas tentativas automáticas e cronogramas escalonados: se a arquitetura exigir a compilação de um commitish do Git em programadores externos, configure novas tentativas automáticas com espera exponencial e escalone os timers cron simultâneos. Para ver exemplos detalhados de código de nova tentativa e etapas de solução de problemas, consulte Não é possível acessar o repositório remoto.
A seguir
- Para saber mais sobre o ciclo de vida do código no Dataform e as diferentes maneiras de configurá-lo, consulte Introdução ao ciclo de vida do código no Dataform.
- Para saber mais sobre as práticas recomendadas para o ciclo de vida do fluxo de trabalho, consulte Práticas recomendadas para o ciclo de vida do fluxo de trabalho.
- Para saber mais sobre os limites de recursos de compilação, consulte Limites de recursos de compilação do Dataform.
- Para saber como conectar um repositório do Dataform a um repositório Git de terceiros, consulte Conectar a um repositório Git de terceiros.
- Para saber mais sobre fluxos de trabalho no Dataform, consulte Visão geral dos fluxos de trabalho.