Criar uma configuração de versão

Este documento mostra como criar uma configuração de versão no Dataform para definir modelos de configurações de compilação, que podem ser executados em uma programação. É possível usar configurações de versão para configurar ambientes de execução, por exemplo, preparo e produção.

Sobre as configurações de versão do Dataform

Para executar fluxos de trabalho SQL no BigQuery, o Dataform compila o código de fluxo de trabalho SQL em um resultado de compilação. Esse processo acontece automaticamente quando você desenvolve um fluxo de trabalho SQL em um espaço de trabalho do Dataform.

As configurações de versão permitem personalizar os resultados da compilação. É possível usá-las para criar ambientes de execução, por exemplo, o preparo.

Configurações da versão

Em uma configuração de versão, você pode definir substituições de compilação de configurações dataform.json, definir variáveis de compilação e definir a frequência de criação dos resultados da compilação.

Uma configuração de versão do Dataform contém as seguintes configurações de compilação:

Configurações da versão
ID da versão, confirmação git para resultados de compilação e frequência de criação de resultados da compilação.
Substituições de compilação
Substituições do projeto do Google Cloud, do prefixo da tabela, do sufixo do esquema e das variáveis de compilação definidas em dataform.json.

Como funciona uma configuração de versão

O Dataform cria resultados de compilação a partir de uma configuração de lançamento na frequência especificada ou quando você aciona a compilação. A frequência é uma configuração opcional e não é necessária para criar uma configuração de versão. É possível acionar manualmente a compilação na página Detalhes da configuração de lançamento ou com a API Dataform releaseConfigs.

Durante a compilação, o Dataform extrai o código do commit do Git especificado no repositório. Em seguida, o Dataform compila o código com as modificações de compilação aplicadas (se houver) e cria o resultado. O resultado da compilação mais recente criado para a configuração da versão é o resultado da compilação em tempo real.

É possível programar execuções de resultados de compilação a partir das configurações de lançamento em configurações de fluxo de trabalho. Também é possível executar uma configuração de versão selecionada fora da programação. Durante uma execução de configuração de fluxo de trabalho, o Dataform executa o resultado da compilação em tempo real a partir da configuração de versão selecionada.

Antes de começar

  1. No Console do Google Cloud, acesse a página do Dataform.

    Acessar a página do Dataform

  2. Selecione ou crie um repositório.

  3. Opcional: para substituir o projeto padrão do Google Cloud na configuração da versão, conceda à sua conta de serviço do Dataform acesso ao projeto do Google Cloud que você planeja usar.

Funções exigidas

Para receber as permissões necessárias para criar uma configuração de versão, peça ao administrador para conceder a você o papel de Editor do Dataform (roles/dataform.editor) nos repositórios. Para obter mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Criar uma configuração de versão

Para criar uma configuração de versão do Dataform, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão e clique em Nova configuração de versão.

  2. No painel Criar uma configuração de versão, defina as configurações de versão.

    1. No campo Código da versão, insira um ID exclusivo para a configuração da versão.

      Os códigos só podem incluir números, letras, hifens e sublinhados.

    2. No campo Git commitish, insira o branch ou SHA do commit do Git para a versão.

    Em um repositório do Dataform não conectado a um repositório remoto, o valor é sempre main.

    1. Opcional: no menu suspenso Frequência, selecione a frequência de criação de resultados da compilação.

  3. Opcional: na seção Compilações de compilação, defina as configurações de compilação.

    1. No campo ID do projeto do Google Cloud, insira o ID do projeto do Google Cloud em que você quer armazenar o resultado da compilação.
    2. No campo Sufixo do esquema, insira um sufixo para anexar ao esquema configurado em dataform.json.
    3. No campo Prefixo da tabela, insira um prefixo para todos os nomes de tabela.

  4. Opcional: na seção Variáveis de compilação, defina variáveis de compilação.

    1. Clique em Adicionar variável.
    2. No campo Chave, insira a variável de compilação.
    3. No campo Value, insira o valor da variável de compilação.
    4. Para adicionar outra variável de compilação, clique em Adicionar variável.

  5. Clique em Criar.

Se você modificar o projeto padrão do Google Cloud, verifique se a conta de serviço do Dataform tem acesso ao projeto do Google Cloud definido na configuração da versão.



Por exemplo, a configuração da versão a seguir cria um resultado de compilação production a partir da ramificação main a cada hora, sem nenhuma modificação de compilação:

  • ID da versão: production
  • Compromisso do Git: main
  • Frequência: por hora
  • nenhuma modificação de compilação

Ver detalhes de uma configuração de versão

É possível ver os seguintes detalhes de uma configuração de versão:

  • Configurações da versão
    • Commitish do Git
    • Timestamp da última compilação
    • Cronograma do cron
    • Substituições de compilação
    • Variáveis de compilação
  • Resultado da compilação em tempo real
    • Carimbo de data/hora da criação
    • Commitish do Git
    • Confirmar SHA
  • Resultados de compilação anteriores

Para ver detalhes de uma configuração de versão, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão.
  2. Selecione uma configuração de versão.
  3. Na página Detalhes da configuração da versão, inspecione os detalhes da configuração.

Acionar manualmente a compilação

Para criar manualmente um resultado de compilação com base em uma configuração de versão selecionada, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão.
  2. Selecione uma configuração de versão.
  3. Na página Detalhes da configuração de lançamento, clique em Nova compilação.

O resultado da compilação recém-criado se torna o resultado ativo para essa configuração de versão.

Acionar a execução de uma configuração de versão

Para acionar a execução do resultado da compilação em tempo real em uma configuração de versão selecionada para o BigQuery, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão e clique em Iniciar execução.
  2. No painel Executar fluxo de trabalho manual, na lista suspensa Configuração da versão, selecione uma configuração de versão.
  3. Selecione as ações do fluxo de trabalho SQL que serão executadas:
    1. Para executar todo o fluxo de trabalho do SQL, clique em Todas as ações.
    2. Para executar as ações selecionadas no fluxo de trabalho SQL, clique em Seleção de ações e selecione as ações.
    3. Para executar ações com tags selecionadas, clique em Seleção de tags e selecione as tags.
  4. Opcional: para executar ações ou tags selecionadas e as dependências delas, selecione a opção Incluir dependências.
  5. Opcional: para executar ações ou tags selecionadas e os dependentes, selecione a opção Incluir dependentes.

  6. Opcional: para recriar todas as tabelas do zero, selecione a opção Executar com atualização completa.

    Sem essa opção, o Dataform atualiza tabelas incrementais sem recriá-las do zero.

  7. Clique em Iniciar execução.

Editar uma configuração de versão

Para editar uma configuração de versão, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão.
  2. Ao lado da configuração de versão que você quer editar, clique no menu Mais e, em seguida, clique em Editar.
  3. No painel Editar versão da configuração, edite as configurações da versão e clique em Salvar.

Excluir uma configuração de versão

Para excluir uma configuração de versão, siga estas etapas:

  1. No seu repositório, acesse Configurações da versão.
  2. Na configuração da versão que você quer excluir, clique no menu Mais e em Excluir.
  3. No pop-up Excluir configuração da versão, clique em Excluir.

A seguir