Criar uma configuração de versão

Neste documento, mostramos como criar uma configuração de versão no Dataform para definir modelos de configurações de compilação, que podem ser executados de acordo com uma programação. É possível usar configurações de versão para configurar 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 preparo.

Configurações da versão

Em uma configuração de versão, você pode definir substituições de compilação das configurações do fluxo de trabalho, definir variáveis de compilação e definir a frequência de criação de resultados de 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, commitish do git para resultados de compilação e frequência de criação desses resultados. A frequência é uma configuração opcional. Se definida, a frequência mínima é 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 nas configurações do fluxo de trabalho.

Como funciona uma configuração de versão

O Dataform cria resultados de compilação 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 é de uma hora. É possível acionar manualmente a compilação 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. O resultado da compilação mais recente criado para a configuração de lançamento é o resultado da compilação em tempo real.

É possível programar execuções de resultados de compilação das configurações de versão nas 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 execução de configuração de fluxo de trabalho, o Dataform executa o resultado da compilação em tempo real da configuração de versão 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 para conceder a você o papel do IAM 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 receber 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 repositório, acesse Lançamentos 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, insira um ID exclusivo para a configuração da versão.

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

    2. No campo Git commitish, insira a ramificação do Git ou o SHA de 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 dos resultados de compilação.

      Se definida, a frequência mínima é 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 definido nas configurações do fluxo de trabalho.
    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 variáveis de compilação.

    1. Clique em Adicionar variável.
    2. No campo Key, 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 definido do Google Cloud na configuração de lançamento.



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 ver 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 compilação mais recente
    • Cronograma do cron
    • Substituições de compilação
    • Variáveis de compilação
  • Resultado da compilação ao vivo
    • Carimbo de data/hora da criação
    • Commitish do Git
    • SHA de confirmação
  • Resultados de compilações anteriores

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

  1. No repositório, acesse Lançamentos 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 resultados de compilação anteriores criados automaticamente pela configuração de lançamento.

A tabela Resultados da compilação manual/API exibe os resultados de compilação criados manualmente ou por chamadas para a API Dataform com base nos últimos 1.000 resultados de compilação no repositório.

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 repositório, acesse Lançamentos 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-criada se torna o resultado ativo para essa configuração de versão.

Os resultados da compilação manual são exibidos na tabela Resultados da compilação manual/API na página Detalhes da configuração da 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 repositório, acesse Lançamentos 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, no menu suspenso 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 ações.
    3. Para executar ações com tags selecionadas, clique em Seleção de tags e selecione as tags.
  5. Opcional: para executar ações ou tags selecionadas e as dependências delas, selecione a opção Incluir dependências.
  6. Opcional: para executar 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 repositório, acesse Lançamentos e programação.
  2. Na configuração de versão que você quer editar, clique no menu Mais e 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 repositório, acesse Lançamentos e programação.
  2. Na configuração de versão que você quer excluir, clique no menu Mais e em Excluir.
  3. Na caixa de diálogo Excluir configuração da versão, clique em Excluir.

A seguir