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 definir ambientes de execução, como 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 do 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á-los para criar ambientes de execução, como o preparo.

Configurações de versão

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

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

Configurações da versão
ID da versão, commitish do git para resultados da compilação e frequência de criação desses resultados. A frequência é uma configuração opcional. Se definida, a frequência mínima será de uma hora.
Substituições de compilação
Substituições do projeto do Google Cloud, prefixo da tabela, sufixo do esquema e variáveis de compilação definidas em workflow_settings.yaml.

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. Se definida, a frequência mínima será de uma hora. É possível acionar a compilação manualmente na página Detalhes da configuração da versão ou acionar a compilação com a API Dataform releaseConfigs.

Durante a compilação, o Dataform extrai o código do commitish Git especificado do seu repositório. Em seguida, o Dataform compila o código com as substituições de compilação aplicadas (se houver) e cria o resultado da compilação. O resultado mais recente da compilação 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 das configurações de versão em configurações do fluxo de trabalho. Também é possível executar uma configuração de versão selecionada fora de qualquer programação. Durante uma configuração de fluxo de trabalho, o Dataform executa o resultado da compilação em tempo real da configuração de lançamento selecionada.

Antes de começar

  1. No Console do Google Cloud, acesse a página 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 de lançamento, 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 que conceda a você o papel do IAM de Editor do Dataform (roles/dataform.editor) nos repositórios. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de 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 Versões e programação.
  2. Na seção Configurações de versão, clique em Criar.

  3. No painel Criar configuração da versão, defina as configurações da versão.

    1. No campo ID da versão, digite um ID exclusivo para a configuração da versão.

      Os IDs podem conter apenas números, letras, hifens e sublinhados.

    2. No campo Git commitish, insira a ramificação do Git ou o SHA de confirmação do Git da versão.

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

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

      Se definida, a frequência mínima será de uma hora.

  4. Opcional: na seção Substituiçõ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 workflow_settings.yaml.
    3. No campo Prefixo da tabela, insira um prefixo para todos os nomes de tabelas.

  5. Opcional: na seção Variáveis de compilação, defina as 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 Valor, insira o valor da variável de compilação.
    4. Para adicionar outra variável de compilação, clique em Adicionar variável.

  6. Clique em Criar.

Se você substituir o projeto padrão do Google Cloud, verifique se sua 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 de versão abaixo cria um resultado de compilação production da ramificação main a cada hora, sem nenhuma substituição de compilação:

  • ID da versão: production
  • Commitish do Git: main
  • Frequência: por hora
  • sem substituições de compilação

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

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

  • Configurações da versão
    • Commitish do Git
    • Carimbo de data/hora do resultado 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
    • SHA de confirmação
  • Resultados da compilação programada anterior

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

  1. No seu repositório, acesse Versões e programaçã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 da versão.

A tabela Resultados da compilação programada exibe os resultados de compilação anteriores criados automaticamente pela configuração da versão. Os resultados de compilação criados manualmente ou por chamadas para a API Dataform não são exibidos na tabela.

Acionar a compilação manualmente

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 Versões e programação.
  2. Selecione uma configuração de versão.
  3. Na página Detalhes da configuração da versão, clique em Nova compilação.

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

Os resultados da compilação manual não são exibidos na tabela Resultados da compilação programada na página Detalhes da 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 Versões e programação.
  2. Na seção Configurações de versão, clique em Iniciar execução.
  3. No painel Executar fluxo de trabalho manual, na lista suspensa Configuração da versão, selecione uma configuração de versão.
  4. Selecione as ações do fluxo de trabalho SQL a serem executadas:
    1. Para executar todo o fluxo de trabalho 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.
    3. Para executar ações com as tags selecionadas, clique em Seleção de tags e selecione as tags.
  5. Opcional: para executar as ações ou tags selecionadas e as dependências delas, selecione a opção Incluir dependências.
  6. Opcional: para executar as ações ou tags selecionadas e os dependentes, selecione a opção Incluir dependentes.

  7. 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.

  8. 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 Versões e programação.
  2. Na configuração da versão que você quer editar, clique no menu Mais e, em seguida, clique em Editar.
  3. No painel Editar configuração da versã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 Versões e programação.
  2. De acordo com a configuração da versão que você quer excluir, clique no menu Mais e, em seguida, clique em Excluir.
  3. Na caixa de diálogo Excluir configuração da versão, clique em Excluir.

A seguir