Práticas recomendadas para repositórios

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

Vista geral das práticas recomendadas de repositórios no Dataform

Esta secção apresenta uma vista geral das práticas recomendadas para gerir 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

A dimensão do repositório afeta vários aspetos 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 quotas e limites da API aos recursos de compilação. Um tamanho grande do repositório pode fazer com que o repositório exceda estas quotas e limites. Isto pode levar à falha na compilação e execução do seu fluxo de trabalho.

Para mitigar esse risco, recomendamos que divida os repositórios grandes. Quando divide um repositório grande, divide um fluxo de trabalho grande num número de fluxos de trabalho mais pequenos alojados em repositórios diferentes e ligados por dependências entre repositórios.

Esta abordagem permite-lhe cumprir as quotas e os limites do Dataform, implementar processos e autorizações detalhados, e melhorar a legibilidade e a colaboração do código base. No entanto, a gestão de repositórios divididos pode ser mais desafiante do que a gestão de um único repositório.

Para saber mais sobre o impacto do tamanho do repositório no Dataform, consulte o artigo Vista geral do tamanho do repositório. Para saber mais acerca das práticas recomendadas para dividir repositórios, consulte o artigo Dividir repositórios.

Práticas recomendadas para a estrutura do repositório

Recomendamos que estruture os ficheiros no diretório definitions de forma a refletir as fases do seu fluxo de trabalho. Tenha em atenção que pode adotar uma estrutura personalizada que se adapte melhor às suas necessidades.

A seguinte estrutura recomendada de subdiretórios definitions reflete as principais fases da maioria dos fluxos de trabalho:

  • sources para armazenar declarações de origens 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 ficheiros adicionais.

Os nomes de todos os ficheiros no Dataform têm de estar em conformidade com as diretrizes de nomenclatura de tabelas do BigQuery. Recomendamos que os nomes dos ficheiros no diretório definitions num repositório do Dataform reflitam a estrutura de subdiretórios.

Para saber mais sobre as práticas recomendadas para estruturar e atribuir nomes a ficheiros num repositório, consulte o artigo Estruturar código num repositório.

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

O ciclo de vida do código predefinido no Dataform consiste nas seguintes fases:

Para gerir o ciclo de vida do código no Dataform, pode criar 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 o artigo Introdução ao ciclo de vida do código no Dataform.

Pode optar por manter os seus ambientes de execução num único repositório ou em vários repositórios.

Ambientes de execução num único repositório

Pode criar ambientes de execução isolados, como desenvolvimento, preparação e produção, num único repositório do Dataform com substituições de compilação do espaço de trabalho e configurações de lançamento.

Pode criar ambientes de execução isolados das seguintes formas:

  • 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, teste e produção por Google Cloud projeto.

Em seguida, pode agendar execuções em ambientes de preparação e produção com configurações de fluxo de trabalho. Recomendamos que acione as execuções manualmente no ambiente de desenvolvimento.

Para saber mais acerca das práticas recomendadas para gerir o ciclo de vida do fluxo de trabalho no Dataform, consulte o artigo Práticas recomendadas para o ciclo de vida do fluxo de trabalho.

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

Para personalizar as autorizações de gestão de identidade e de acesso para cada fase do ciclo de vida do código, pode criar várias cópias de um repositório e armazená-las em diferentes Google Cloud projetos.

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

Nesta abordagem, recomendamos que mantenha 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 do fluxo de trabalho.

Vista geral do tamanho do repositório

Esta secção ajuda a compreender como o tamanho do repositório afeta o desenvolvimento do fluxo de trabalho e a utilização de recursos de compilação do Dataform, e como estimar a utilização de recursos de compilação do seu repositório.

Acerca do tamanho do repositório no Dataform

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

  • Colaboração. Vários colaboradores a trabalhar num repositório grande podem criar um número excessivo de pedidos de obtenção, o que aumenta o risco de conflitos de união.

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

  • Processos de desenvolvimento. Algumas áreas de um fluxo de trabalho grande num único repositório podem exigir autorizações ou processos personalizados, como o agendamento, que são diferentes das autorizações e dos processos aplicados ao resto do fluxo de trabalho. Um tamanho grande do repositório 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 utilização aos recursos de compilação. Um repositório grande pode levar à ultrapassagem destes limites, o que faz 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 implementa recursos no BigQuery. Quanto maior for o repositório, mais tempo o Dataform demora a executá-lo.

Se o tamanho grande do repositório afetar negativamente o seu desenvolvimento no Dataform, pode dividir o repositório em vários repositórios mais pequenos.

Acerca dos limites de recursos de compilação de repositórios

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 seu repositório. A isto chama-se resultado de compilação. O Dataform aplica limites de utilização aos recursos de compilação.

O seu repositório pode exceder os limites de utilização pelos seguintes motivos:

  • Um erro de repetição infinita no código do repositório.
  • Um erro de fuga de memória no código do repositório.
  • Um tamanho do repositório grande, aproximadamente mais de 1000 ações de fluxo de trabalho.

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

Estime a utilização de recursos de compilação do seu repositório

Pode estimar a utilização dos seguintes recursos de compilação para o seu repositório:

  • Utilização do tempo da CPU.
  • Tamanho máximo total dos dados serializados do gráfico de ações gerado definido no seu repositório.

Para obter uma aproximação aproximada da utilização atual do tempo da CPU de compilação para a compilação do seu repositório, pode cronometrar a compilação do seu fluxo de trabalho do Dataform numa máquina Linux ou macOS local.

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

    time dataform compile

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

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

Pode tratar o resultado real como um indicador aproximado da utilização do tempo da CPU para a compilação do seu repositório.

Para obter uma aproximação aproximada do tamanho total do gráfico gerado de ações no seu repositório, pode escrever o resultado do gráfico num ficheiro JSON. Pode considerar o tamanho do ficheiro JSON não comprimido como um indicador aproximado do tamanho total do gráfico.

  • Para escrever o resultado do gráfico compilado do seu fluxo de trabalho num ficheiro JSON, no seu repositório, execute o seguinte comando da CLI do Dataform:

    dataform compile --json > graph.json

Dividir repositórios

Esta secção aborda estratégias para dividir um repositório do Dataform e gerir dependências entre repositórios.

Os repositórios são as unidades principais no Dataform. Um repositório armazena todos os ficheiros SQLX e JavaScript que compõem o seu fluxo de trabalho, bem como os ficheiros de configuração e os pacotes do Dataform. Pode armazenar um fluxo de trabalho num único repositório ou dividi-lo entre vários repositórios.

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

  • Aderir aos limites do Dataform na utilização de recursos de compilação. Dividir um fluxo de trabalho grande em vários repositórios mais pequenos reduz o risco de exceder os limites do Dataform nos recursos de compilação.
  • Ajustar os processos. Pode definir processos, como regras de integração contínua (IC), individualmente para cada fragmento dividido do seu fluxo de trabalho e para a equipa que o está a desenvolver.
  • Ajustar as autorizações. Pode definir autorizações individualmente para cada fragmento do fluxo de trabalho e para a equipa que o está a desenvolver 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.
  • Melhorar a legibilidade da base de código. Dividir os ficheiros que compõem um fluxo de trabalho grande em vários repositórios facilita a navegação em cada repositório individualmente do que navegar em 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 contínua e desenvolvimento contínuo (CI/CD) necessária para cada repositório do Dataform e o respetivo repositório Git.
  • É necessária uma configuração de agendamento personalizada para cada repositório do Dataform e o respetivo repositório Git.
  • Dificuldade em gerir as dependências entre os objetos do seu 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 de 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

Quando divide um repositório, divide os ficheiros que compõem um fluxo de trabalho SQL principal em fluxos de trabalho secundários mais pequenos alojados em repositórios do Dataform separados.

Pode optar por dividir um repositório de uma das seguintes formas:

  • Um repositório por equipa 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 os conteúdos do repositório central como origens de dados.

Para alojar o fluxo de trabalho principal numa plataforma de alojamento Git de terceiros, tem de associar individualmente cada um dos repositórios separados que contêm fluxos de trabalho secundários a um repositório Git de terceiros dedicado.

Gerir dependências entre repositórios

A forma mais eficiente de dividir um repositório é dividir o fluxo de trabalho SQL principal em fluxos de trabalho secundários autónomos, criando repositórios independentes. Um repositório independente não usa o conteúdo de um repositório diferente como origem de dados. Esta abordagem não requer a gestão de dependências entre repositórios.

Quando não pode evitar dependências entre repositórios, pode geri-las dividindo um repositório numa sucessão de repositórios, em que um repositório depende do seu antecessor e é uma origem de dados para o seu sucessor. A sucessão de repositórios e respetivas dependências tem de refletir melhor a estrutura do fluxo de trabalho principal.

Pode criar dependências entre repositórios com declarações de origens de dados do Dataform. Pode declarar um tipo de tabela do BigQuery de um repositório do Dataform diferente como uma origem de dados no repositório que está a ser editado. Depois de declarar uma origem de dados, pode referenciá-la como qualquer outra ação do fluxo de trabalho do Dataform e usá-la para desenvolver o seu fluxo de trabalho.

Quando agenda a execução de um fluxo de trabalho dividido entre repositórios com dependências entre repositórios, tem de executar os repositórios um a um por ordem das dependências entre repositórios.

Recomendamos que evite dividir um repositório num grupo de repositórios com dependências bidirecionais. Uma dependência bidirecional entre repositórios ocorre quando um repositório é uma origem de dados para um repositório diferente e também usa esse repositório como uma origem de dados. As dependências bidirecionais entre repositórios complicam o agendamento e a execução do fluxo de trabalho principal, bem como os processos de desenvolvimento.

Estruturar código num repositório

Esta secção descreve as práticas recomendadas para estruturar e atribuir nomes a ficheiros de fluxo de trabalho no diretório definitions raiz de um repositório do Dataform. A estrutura recomendada do diretório definitions reflete as fases de um fluxo de trabalho. Pode adotar qualquer estrutura que se ajuste às necessidades da sua empresa.

Recomendamos que estruture o código do fluxo de trabalho no diretório definitions pelos seguintes motivos:

  • Melhorar a colaboração na base de código, atribuindo equipas a partes selecionadas do seu fluxo de trabalho.
  • Melhorar a capacidade de manutenção do fluxo de trabalho em caso de alterações organizacionais.
  • Melhorar a navegação no seu código base.
  • Melhorar a escalabilidade da base de código.
  • Minimizar as despesas gerais administrativas da sua equipa.

O diretório definitions raiz num repositório do Dataform contém código que cria elementos do seu fluxo de trabalho. Pode organizar os ficheiros no diretório definitions numa estrutura de diretórios que reflita a estrutura do fluxo de trabalho.

Quando desenvolve um fluxo de trabalho, declara tabelas de origem e transforma-as para criar tabelas de saída que pode usar para fins empresariais ou de estatísticas.

Pode distinguir três fases principais de um fluxo de trabalho:

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

A seguinte estrutura de subdiretórios no diretório definitions reflete as fases principais de um fluxo de trabalho:

sources
Declarações de origens de dados e transformação básica de dados de origem, por exemplo, filtragem.
intermediate
Tabelas e ações que leem a partir de sources e transformam dados antes de usar os dados transformados para definir tabelas outputs. Normalmente, as tabelas não são expostas a processos ou ferramentas adicionais, como ferramentas de Business Intelligence (BI), depois de o Dataform as executar no BigQuery.
outputs
Definições de tabelas consumidas por processos ou ferramentas, como a inteligência empresarial, depois de o Dataform as executar no BigQuery.
extra
Ficheiros fora do pipeline principal do seu fluxo de trabalho, por exemplo, ficheiros que contêm dados do fluxo de trabalho preparados para utilização adicional, como a aprendizagem automática. Um subdiretório opcional e personalizado.

Práticas recomendadas para sources

O subdiretório sources contém a primeira fase 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 origens de dados e tabelas que filtram, categorizam, convertem ou mudam o nome das colunas.

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

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

Se declarar origens de dados de vários conjuntos, por exemplo, o Google Ads ou o Google Analytics, dedique um subdiretório a cada conjunto.

O exemplo seguinte mostra uma estrutura de subdiretórios de sources com dois conjuntos de origens:

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 declarar várias tabelas de origens de dados no mesmo esquema, pode consolidar as respetivas declarações num único ficheiro JavaScript.

Para mais informações sobre como criar declarações de origens de dados com JavaScript, consulte Crie fluxos de trabalho exclusivamente com JavaScript.

O seguinte exemplo de código mostra várias origens de dados num esquema, declaradas num único ficheiro JavaScript:

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

Para proteger o seu fluxo de trabalho contra alterações à origem de dados, pode criar uma vista para cada declaração de origem de dados, por exemplo, analytics_users_filtered.sqlx. A vista pode conter a filtragem e a formatação básicas dos dados de origem. Armazene as vistas na subdiretoria sources.

Em seguida, quando criar tabelas intermediate ou outputs, faça referência às vistas em vez das tabelas de origem não processadas. Esta abordagem permite-lhe testar as tabelas de origem. Caso uma tabela de origem seja alterada, pode modificar a respetiva vista, por exemplo, adicionando filtros ou reformulando dados.

Práticas recomendadas para intermediate

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

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

Use tabelas intermediate para criar tabelas outputs. Normalmente, intermediate as tabelas não são usadas para fins adicionais, por exemplo, análise de dados, depois de o Dataform as executar no BigQuery. Pode considerar as tabelas intermediate como a lógica de transformação de dados que permite a criação de tabelas de saída.

Recomendamos que 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 resultados para fins empresariais a partir dos dados transformados.

No diretório outputs, armazene tabelas que planeia usar em processos ou ferramentas adicionais depois de o Dataform as executar no BigQuery, por exemplo, relatórios ou painéis de controlo. Normalmente, as tabelas no diretório outputs consultam dados das tabelas intermediate.

Agrupe as tabelas outputs pela entidade empresarial à qual estão relacionadas, por exemplo, marketing, encomendas ou estatísticas. Dedique um subdiretório a cada entidade empresarial.

Para armazenar tabelas de resultados separadamente no BigQuery, pode configurar um esquema dedicado para tabelas de resultados. Para obter instruções sobre como configurar o esquema da tabela, consulte Substitua as definições da tabela.

O exemplo seguinte mostra uma estrutura de subdiretórios 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 documente e teste todas as tabelas outputs.

Estratégia de nomenclatura

Os nomes de todos os ficheiros no Dataform têm de estar em conformidade com as diretrizes de nomenclatura de tabelas do BigQuery.

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

No subdiretório sources, os nomes dos ficheiros devem apontar para a origem a que o ficheiro está relacionado. Adicione o nome da fonte como prefixo aos nomes dos ficheiros, por exemplo, analytics_filtered.sqlx

No subdiretório intermediate, os nomes dos ficheiros devem identificar o subdiretório, para que os colaboradores possam distinguir claramente os ficheiros intermediate. Selecione um prefixo exclusivo e aplique-o apenas aos ficheiros no diretório intermediate —por exemplo, stg_ads_concept.sqlx.

No subdiretório outputs, os nomes de ficheiros devem ser concisos. Por exemplo: orders.sqlx. Se tiver outputs tabelas 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 seguinte mostra uma estrutura de subdiretórios no diretório definitions com nomes de ficheiros 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

O que se segue?