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 suas necessidades de negócios.
É recomendá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.
- Melhoria da manutenção do fluxo de trabalho do SQL no caso de alterações organizacionais.
- Melhorar a navegação pela base de código.
- Melhorando a escalonabilidade da base de código.
- Minimizar a sobrecarga administrativa para sua equipe.
Estrutura recomendada do diretório definitions
O diretório raiz definitions em um repositório do Dataform contém código que cria elementos do fluxo de trabalho do SQL. É possível organizar
arquivos no diretório definitions em uma estrutura de diretórios
que reflete 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:
- Declaração de fontes de dados
- Transformação de dados de origem
- Definição de tabelas de saída a partir dos dados de origem transformados
A seguinte estrutura de subdiretórios no diretório definitions reflete os principais estágios de um fluxo de trabalho SQL:
sources- Declarações da fonte de dados e transformação básica dos dados de origem, por exemplo, filtragem.
intermediate- Tabelas e ações que leem de
sourcese transformam dados antes de você usar os dados transformados para definir tabelasoutputs. Normalmente, as tabelas 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, após a execução do Dataform no BigQuery.
extra- Arquivos fora do pipeline principal do fluxo de trabalho 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 o primeiro estágio do fluxo de trabalho SQL: declaração e transformação básica dos dados de origem.
No subdiretório sources, armazene declarações de fonte de dados e tabelas que filtram, categorizam, transmitem ou renomeiam colunas.
Evite armazenar tabelas que combinem dados de várias fontes.
Transformar 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 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 fonte de dados dentro do mesmo esquema, poderá consolidar as declarações em um único arquivo JavaScript. Em um arquivo JavaScript, é possível armazenar várias declarações de fonte de dados. Para mais informações sobre como criar declarações de fonte de dados com JavaScript, consulte Criar fluxos de trabalho SQL do Dataform com JavaScript.
A 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 alterações na fonte de dados, crie uma visualização
para cada declaração da fonte, por exemplo, analytics_users_filtered.sqlx.
A visualização pode conter filtragem e 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 for alterada, será possível modificar a visualização adicionando, por exemplo, filtros ou retransmissão de dados.
Práticas recomendadas para intermediate
O subdiretório intermediate contém o segundo estágio do fluxo de trabalho SQL: transformação e agregação de dados de origem de uma ou várias origens.
No subdiretório intermediate, armazene arquivos que transformem dados de origem de uma ou várias origens de maneira significativa no subdiretório sources, por exemplo, tabelas que mesclam dados. As tabelas no subdiretório intermediate normalmente 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 do SQL: criação de tabelas de saída para seus negócios a partir de dados transformados.
No diretório outputs, armazene tabelas que você planeja usar em processos ou ferramentas adicionais depois que o Dataform as executa no BigQuery, por exemplo, relatórios ou painéis. As tabelas no diretório outputs normalmente consultam dados de intermediate.
Agrupe as tabelas outputs pela entidade comercial a que estão relacionadas, por exemplo, marketing, pedidos ou análises. Dedique um subdiretório para 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 definir 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 de 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 a que o arquivo está relacionado. Adicione o nome da origem como prefixo dos nomes de arquivo, por exemplo, analytics_filtered.sqlx
No subdiretório intermediate, os nomes de arquivo precisam identificá-lo 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 dos arquivos precisam ser concisos, por exemplo, orders.sqlx. Se você tiver tabelas outputs com os mesmos nomes em
subdiretórios de entidade 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 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
- Para saber mais sobre os fluxos de trabalho SQL no Dataform, consulte Introdução aos fluxos de trabalho SQL.
- Para saber mais sobre repositórios do Dataform, consulte Introdução aos repositórios.
- Para saber mais sobre como dividir repositórios, consulte Introdução à divisão de repositórios.