Configurar compilações

Este documento mostra como fazer o seguinte no Dataform:

Antes de começar

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

    Acessar o Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. 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 que você planeja usar.

Funções exigidas

Para receber as permissões necessárias para concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM nos repositórios:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

Introdução ao ciclo de vida do código no Dataform

Esta seção descreve o ciclo de vida do código no Dataform e as maneiras de configurar a compilação e a execução no Dataform.

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

Desenvolvimento
Você desenvolve um fluxo de trabalho em um espaço de trabalho do Dataform.
Compilação

O Dataform compila o código do fluxo de trabalho no seu espaço de trabalho para SQL em tempo real, criando um resultado de compilação do espaço de trabalho que pode ser executado no BigQuery. O Dataform usa as configurações que você define no arquivo de configurações do fluxo de trabalho para criar o resultado da compilação.

A compilação do Dataform é hermética para garantir a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação SQL sempre. O Dataform compila seu código em um ambiente de sandbox sem acesso à Internet. Nenhuma ação adicional, como chamar APIs externas, está disponível durante a compilação.

Execução

Em uma invocação de fluxo de trabalho, o Dataform executa o resultado da compilação do espaço de trabalho no BigQuery.

Para adaptar o ciclo de vida de código do Dataform às suas necessidades, configure o resultado da compilação para influenciar onde e como o Dataform executa seu fluxo de trabalho. Em seguida, é possível acionar ou programar manualmente execuções para influenciar quando o Dataform executa todo o fluxo de trabalho ou os elementos selecionados.

Formas de configurar a compilação do Dataform

Por padrão, o Dataform usa as configurações no arquivo de configurações do fluxo de trabalho para criar resultados de compilação. É possível substituir as configurações padrão com substituições de compilação para criar resultados personalizados. Em seguida, você pode acionar manualmente uma execução de um resultado de compilação personalizado ou programar execuções.

O Dataform oferece as seguintes opções para configurar os resultados da compilação:

Substituições de compilação do espaço de trabalho
É possível configurar substituições de compilação que se aplicam a todos os espaços de trabalho em um repositório. É possível usar substituições de compilação do espaço de trabalho para criar ambientes de desenvolvimento isolados.
Configurações da versão
É possível criar configurações de lançamento para configurar modelos para criar resultados de compilação de um repositório do Dataform. Em seguida, crie uma configuração de fluxo de trabalho para programar execuções de resultados de compilação criados em uma configuração de lançamento selecionada.
Substituições de compilação da API Dataform
É possível transmitir solicitações da API Dataform no terminal para criar e executar um único resultado de compilação com substituições de compilação.

Configurar substituições de compilação do espaço de trabalho

Com as substituições de compilação do espaço de trabalho, é possível criar substituições de compilação para todos os espaços de trabalho em um repositório do Dataform. É possível criar uma configuração de substituições de compilação do espaço de trabalho para cada repositório.

Quando você aciona manualmente uma execução em um espaço de trabalho em um repositório com substituições de compilação do espaço de trabalho, o Dataform aplica essas substituições ao resultado da compilação do espaço de trabalho.

É possível configurar as seguintes substituições de compilação do espaço de trabalho:

  • Projeto do Google Cloud em que o Dataform executa o conteúdo do espaço de trabalho
  • Prefixo da tabela
  • Sufixo do esquema

É possível usar substituições de compilação do espaço de trabalho para criar ambientes de desenvolvimento isolados isolando os resultados de compilação do espaço de trabalho no BigQuery com substituições de compilação dinâmicas. As substituições de compilação de prefixo de tabela dinâmica e sufixo de esquema contêm a variável ${workspaceName}. Quando você aciona uma execução em um espaço de trabalho, o Dataform substitui a variável ${workspaceName} pelo nome do espaço de trabalho atual, criando substituições de compilação exclusivas para o espaço de trabalho.

Não é possível programar execuções de resultados de compilação criados com substituições de compilação do espaço de trabalho.

Criar configurações de versão

Com as configurações de versão, é possível definir modelos de configurações para criar resultados de compilação de repositórios.

Em uma configuração de versão, é possível configurar substituições de compilação de configurações de fluxo de trabalho, variáveis de compilação e a frequência de criação de resultados de compilação de todo o repositório.

Em uma configuração de versão, é possível configurar as seguintes substituições de compilação:

É possível criar várias configurações de lançamento em um repositório do Dataform, uma para cada fase do ciclo de vida de desenvolvimento, criando resultados de compilação de repositório isolados.

Em seguida, você pode criar configurações de fluxo de trabalho para programar execuções de resultados de compilação criados em uma configuração de lançamento selecionada.

Também é possível ativar manualmente a execução de um resultado de compilação em uma configuração de lançamento selecionada.

Configurar um único resultado de compilação com substituições de compilação da API Dataform

Ao transmitir solicitações da API Dataform no terminal, é possível configurar substituições de compilação para um único resultado de compilação.

Na solicitação compilationResults.create, é possível criar um único resultado de compilação de um espaço de trabalho do Dataform ou de um commit do Git especificado.

No objeto CodeCompilationConfig da solicitação compilationResults.create, é possível configurar substituições de compilação para a solicitação de compilação.

É possível configurar as seguintes substituições de compilação da API Dataform:

Lembre-se de que as substituições de compilação da API Dataform se aplicam a um único resultado de compilação e a uma única execução. Não é possível usá-los para programar execuções do Dataform.

É possível executar um resultado de compilação na solicitação workflowInvocations.create.

Formas de configurar a execução do Dataform

O Dataform oferece as seguintes opções para configurar a execução:

Execução manual em um espaço de trabalho
É possível acionar manualmente a execução instantânea de um fluxo de trabalho em um espaço de trabalho do Dataform, fora de qualquer programação. É possível executar ações selecionadas no fluxo de trabalho.
Configurações do fluxo de trabalho
É possível programar execuções de resultados de compilação criados em uma configuração de versão selecionada. É possível selecionar ações de fluxo de trabalho para execução e definir a frequência e o fuso horário das execuções.

Acionar a execução instantânea em um espaço de trabalho

Em um espaço de trabalho do Dataform, é possível acionar manualmente a execução instantânea de um fluxo de trabalho no espaço de trabalho, fora de qualquer programação.

É possível executar manualmente os seguintes elementos do fluxo de trabalho no seu espaço de trabalho:

Se o repositório tiver substituições de compilação do espaço de trabalho, você poderá conferir quais substituições de compilação o Dataform vai aplicar ao resultado da compilação do espaço de trabalho.

Criar configurações de fluxo de trabalho

Com as configurações de fluxo de trabalho, é possível programar execuções de resultados de compilação de uma configuração de lançamento selecionada. É possível criar várias configurações de fluxo de trabalho em um repositório do Dataform.

Em uma configuração de fluxo de trabalho, é possível definir as seguintes configurações de execução:

  • Configuração de versão de compilação aplicada.
  • Seleção de ações do fluxo de trabalho a serem executadas.
  • Programação e fuso horário das execuções.

Você pode selecionar as seguintes ações do fluxo de trabalho para serem executadas:

  • Todas as ações
  • Ações selecionadas
  • Ações com tags selecionadas

Em seguida, durante uma execução programada da configuração do fluxo de trabalho, o Dataform implanta a seleção de ações do resultado da compilação aplicada no BigQuery.

As configurações de versão e de fluxo de trabalho do Dataform permitem configurar a compilação e programar execuções no Dataform, sem precisar depender de outros serviços.

Recursos do ciclo de vida expirados

O Dataform armazena resultados de compilação e invocações de fluxo de trabalho por um período específico.

Expiração de invocações de fluxo de trabalho

As invocações de fluxo de trabalho expiram após 90 dias ou quando são excluídas manualmente.

Em uma configuração de fluxo de trabalho, é possível conferir uma lista das invocações de fluxo de trabalho mais recentes criadas pela configuração. Quando uma invocação de fluxo de trabalho criada por uma configuração de fluxo de trabalho expira, o Dataform remove essa invocação da lista de invocações recentes.

Validade dos resultados da compilação

A expiração dos resultados de compilação depende se eles foram criados em um espaço de trabalho de desenvolvimento, em uma configuração de lançamento ou por uma invocação de fluxo de trabalho.

Quando você desenvolve um fluxo de trabalho em um espaço de trabalho do Dataform, ele compila seu código em um resultado de compilação em tempo real para fornecer validação de consulta. Os resultados de compilação criados dessa forma expiram após 24 horas.

Em uma configuração de lançamento, o resultado de compilação mais recente se torna o resultado de compilação em tempo real. Um novo resultado de compilação substitui o resultado de compilação atual. O Dataform retém o resultado da compilação em tempo real até que seja substituído por um novo resultado. Um resultado de compilação substituído expira em até 24 horas.

O Dataform remove os resultados de compilação expirados da lista de resultados de compilação anteriores na página Detalhes de uma configuração de lançamento.

O Dataform retém os resultados da compilação criados por invocações de fluxo de trabalho por todo o ciclo de vida da invocação do fluxo de trabalho, até 24 horas após a invocação do fluxo de trabalho expirar ou ser excluída.

Criar substituições de compilação do espaço de trabalho

As seções a seguir mostram como criar substituições de compilação de espaço de trabalho para isolar tabelas e visualizações criadas nos espaços de trabalho do Dataform no BigQuery. É possível usar substituições de compilação de espaço de trabalho para criar ambientes de desenvolvimento isolados do Dataform.

Quando você desenvolve um código de fluxo de trabalho em um espaço de trabalho do Dataform, ele compila o código no seu espaço de trabalho em tempo real para criar um resultado de compilação do espaço de trabalho. O Dataform usa as configurações definidas no arquivo de configurações do fluxo de trabalho para criar o resultado da compilação do espaço de trabalho. Em seguida, quando você aciona a execução em um espaço de trabalho, o Dataform executa o resultado da compilação do espaço de trabalho no BigQuery.

Para substituir as configurações padrão definidas nas configurações do fluxo de trabalho em todos os espaços de trabalho do repositório, crie substituições de compilação do espaço de trabalho.

Com as substituições de compilação do espaço de trabalho, é possível substituir as seguintes configurações para todos os espaços de trabalho no repositório:

Projeto
O projeto do Google Cloud em que o Dataform executa o resultado da compilação do espaço de trabalho, definido em workflow_settings.yaml como defaultProject ou em dataform.json como defaultDatabase.
Prefixo da tabela
O prefixo personalizado adicionado a todos os nomes de tabela em todos os espaços de trabalho no repositório.
Sufixo do esquema
O sufixo personalizado anexado ao esquema de tabelas. Defina como defaultDataset em workflow_settings.yaml, defaultSchema em dataform.json ou no parâmetro schema no bloco config de uma tabela.

Para criar ambientes de desenvolvimento isolados, é possível isolar espaços de trabalho com substituições de compilação exclusivas. É possível modificar dinamicamente as substituições de compilação do prefixo da tabela e do sufixo do esquema com a variável ${workspaceName}.

Quando você aciona manualmente a execução em um espaço de trabalho, a variável ${workspaceName} injeta o nome do espaço de trabalho nas substituições de compilação do espaço de trabalho.

Quando você define ${workspaceName} como o prefixo da tabela, o Dataform adiciona o nome do espaço de trabalho aos nomes de todas as tabelas no espaço de trabalho. Após a execução, no BigQuery, é possível identificar de qual espaço de trabalho uma tabela é originada.

Quando você define ${workspaceName} como o sufixo do esquema, o Dataform anexa o nome do espaço de trabalho a defaultSchema, criando um esquema personalizado dedicado ao espaço de trabalho. Após a execução, no BigQuery, é possível localizar todas as tabelas executadas em um espaço de trabalho específico no esquema dedicado.

Exemplo de substituições de compilação de espaço de trabalho dinâmico

O exemplo a seguir mostra substituições de compilação de espaço de trabalho dinâmico aplicadas a um repositório que contém espaços de trabalho com o nome de desenvolvedores que trabalham no repositório: Sasha e Kai.

O objetivo das substituições de compilação do espaço de trabalho neste exemplo é criar ambientes de desenvolvimento isolados para Sasha e Kai.

As seguintes configurações padrão são definidas em workflow_settings.yaml:

  • defaultProject : analytics
  • defaultDataset: dataform

As substituições de compilação de espaço de trabalho a seguir criam um prefixo de tabela dinâmico e um sufixo de esquema para cada espaço de trabalho no repositório:

  • ID do projeto do Google Cloud: analytics_dev
  • Prefixo da tabela: ${workspaceName}
  • Sufixo do esquema: ${workspaceName}

Quando Sasha aciona manualmente a execução no espaço de trabalho Sasha, o Dataform executa o conteúdo com as seguintes configurações:

  • Projeto do Google Cloud: analytics_dev
  • Esquema: dataform_sasha
  • Nomes de tabelas: sasha_name, por exemplo, sasha_orders

Quando Kai aciona manualmente a execução no espaço de trabalho Kai, o Dataform executa o conteúdo com as seguintes configurações:

  • Projeto do Google Cloud: analytics_dev
  • Esquema: dataform_kai
  • Nomes de tabelas: kai_name, por exemplo, kai_orders

Criar substituições de compilação do espaço de trabalho

Para criar substituições de compilação do espaço de trabalho do Dataform, siga estas etapas:

  1. No repositório, acesse Configurações.
  2. Clique em Editar.
  3. No painel Substituições de compilação do espaço de trabalho, no campo ID do projeto do Google Cloud, insira o ID do projeto.
  4. No campo Prefixo da tabela, insira um prefixo para todos os nomes de tabela.
    1. Opcional: para criar um prefixo de tabela dinâmica exclusivo para cada espaço de trabalho, insira ${workspaceName} como o prefixo da tabela.
  5. No campo Sufixo do esquema, insira um sufixo para anexar ao esquema da tabela ou visualização criada.
    1. Opcional: para criar um sufixo de esquema dinâmico exclusivo para cada espaço de trabalho, insira ${workspaceName} como o sufixo da tabela.
  6. Clique em Salvar.

O Dataform aplica substituições de compilação de espaço de trabalho a todos os espaços de trabalho no repositório.

Editar substituições de compilação do espaço de trabalho

Para editar substituições de compilação do espaço de trabalho do Dataform, siga estas etapas:

  1. No repositório, acesse Configurações.
  2. Clique em Editar.
  3. Edite as substituições de compilação do espaço de trabalho e clique em Salvar.

Excluir substituições de compilação do espaço de trabalho

Para excluir substituições de compilação do espaço de trabalho do Dataform, siga estas etapas:

  1. No repositório, acesse Configurações.
  2. Clique em Editar.
  3. No painel Substituições de compilação do espaço de trabalho, clique em Limpar tudo e em Salvar.

Configurar substituições de compilação com a API Dataform

Nesta seção, mostramos como criar e executar um resultado de compilação com substituições de compilação usando a API Dataform.

Sobre as substituições de compilação da API Dataform

Para executar o fluxo de trabalho, o Dataform compila o código para SQL e cria um resultado de compilação. Em seguida, durante uma invocação de fluxo de trabalho, o Dataform executa o resultado da compilação no BigQuery.

Por padrão, o Dataform usa as configurações no arquivo de configurações do fluxo de trabalho para criar o resultado da compilação. Para isolar os dados executados em diferentes estágios do ciclo de vida de desenvolvimento, é possível substituir as configurações padrão com substituições de compilação.

Ao transmitir solicitações da API Dataform no terminal, você pode criar e executar um único resultado de compilação com substituições de compilação. É possível criar um resultado de compilação de um espaço de trabalho ou de um committish do Git selecionado.

Para criar um resultado de compilação com substituições de compilação, é necessário gerar a solicitação compilationResults.create da API Dataform. Na solicitação, é necessário especificar uma origem, que precisa ser um espaço de trabalho ou um commitish do Git, para que o Dataform seja compilado no resultado da compilação. No objeto CodeCompilationConfig da solicitação compilationResults.create, é possível configurar substituições de compilação.

Em seguida, execute o resultado da compilação criada em uma solicitação workflowInvocations.create da API Dataform.

É possível configurar as seguintes substituições de compilação usando a API Dataform:

Projeto do Google Cloud
O projeto em que o Dataform executa o resultado da compilação, definido no arquivo workflow_settings.yaml como a propriedade defaultProject ou no arquivo dataform.json como a propriedade defaultDatabase.
Prefixo da tabela
O prefixo personalizado adicionado a todos os nomes de tabela no resultado da compilação.
Sufixo do esquema
O sufixo personalizado anexado ao esquema de tabelas definido na propriedade defaultDataset do arquivo workflow_settings.yaml, na propriedade defaultSchema do arquivo dataform.json ou no parâmetro schema do bloco config de uma tabela.
Valor de uma variável de compilação
O valor de uma variável de compilação a ser usado no resultado da compilação. Você pode usar variáveis de compilação para executar tabelas condicionalmente.

Como alternativa às substituições de compilação da API Dataform que só podem ser usadas para um resultado de compilação, é possível configurar substituições de compilação do workspace no console do Google Cloud.

Para saber mais sobre maneiras alternativas de configurar substituições de compilação no Dataform, consulte Introdução ao ciclo de vida do código.

Definir uma origem de resultado de compilação

Para gerar a solicitação compilationResults.create da API Dataform, é necessário especificar uma origem para o resultado da compilação.

É possível definir um espaço de trabalho do Dataform ou uma ramificação, tag ou SHA de confirmação do Git como a origem na solicitação compilationResults.create.

Definir um espaço de trabalho como uma origem de resultados de compilação

  • Na solicitação compilationResults.create, preencha a propriedade workspace com o caminho de um espaço de trabalho do Dataform selecionado no seguinte formato:

    {
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

    Substitua:

    • PROJECT_NAME: o nome do seu projeto do Google Cloud.
    • LOCATION: o local do repositório do Dataform, definido nas configurações do fluxo de trabalho.
    • REPOSITORY_NAME: o nome do repositório do Dataform.
    • WORKSPACE_NAME: o nome do seu espaço de trabalho do Dataform.

O exemplo de código a seguir mostra a propriedade workspace na solicitação compilationResults.create definida para um espaço de trabalho chamado "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Definir um commitish do Git como uma origem de resultado de compilação

  • Na solicitação compilationResults.create, preencha a propriedade gitCommitish com a ramificação, a tag ou o SHA de confirmação selecionados no formato a seguir:

    {
  "gitCommitish": "GIT_COMMITISH"
}

    Substitua GIT_COMMITISH pela ramificação ou tag do Git selecionada ou por um SHA de confirmação do Git para o resultado da compilação.

O exemplo de código abaixo mostra a propriedade gitCommitish na solicitação compilationResults.create definida como "staging":

{
  "gitCommitish": "staging"
}

Substituir o projeto padrão

Para criar tabelas de preparação ou produção em um projeto do Google Cloud separado do projeto usado para desenvolvimento, é possível transmitir um ID de projeto diferente no objeto CodeCompilationConfig na solicitação compilationResults.create da API Dataform.

A transmissão de um ID de projeto padrão separado na solicitação compilationResults.create substitui o ID de projeto padrão configurado no arquivo de configurações do fluxo de trabalho, mas não substitui os IDs de projeto configurados em tabelas individuais.

  • Para substituir o ID do projeto padrão, defina a propriedade defaultDatabase como o ID do projeto selecionado no objeto CodeCompilationConfig no seguinte formato:

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

    Substitua PROJECT_NAME pelo ID do projeto que você quer definir para o resultado da compilação.

Adicionar um prefixo de tabela

Para identificar rapidamente as tabelas no resultado da compilação, adicione um prefixo a todos os nomes de tabela no resultado da compilação transmitindo o prefixo da tabela no objeto CodeCompilationConfig na solicitação compilationResults.create da API Dataform.

  • Para adicionar um prefixo de tabela, defina a propriedade tablePrefix no objeto CodeCompilationConfig no seguinte formato:

    {
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

    Substitua PREFIX pelo prefixo que você quer anexar, por exemplo, staging.

    Por exemplo, se o nome da tabela for table_name, o Dataform cria tabelas com o nome staging_table_name.

Anexar um sufixo de esquema

Para separar dados de desenvolvimento, de fase de testes e de produção, você pode anexar um sufixo a esquemas em um resultado de compilação transmitindo o sufixo do esquema no objeto CodeCompilationConfig na solicitação compilationResults.create da API Dataform.

  • Para anexar um sufixo de esquema, defina a propriedade schemaSuffix no objeto CodeCompilationConfig no seguinte formato:

    {
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

    Substitua SUFFIX pelo sufixo que você quer anexar, por exemplo, _staging.

    Por exemplo, se a propriedade defaultDataset no arquivo workflow_settings.yaml estiver definida como dataform, o Dataform vai criar tabelas no esquema dataform_staging.

Executar arquivos selecionados condicionalmente com variáveis de compilação

Para executar uma tabela selecionada apenas em uma configuração de execução específica, crie uma variável de compilação para a configuração de execução e transmita o valor dela no objeto CodeCompilationConfig na solicitação compilationResults.create da API Dataform.

Para executar uma tabela condicionalmente em uma configuração de execução específica usando a API Dataform, siga estas etapas:

  1. Crie uma variável de compilação e adicione às tabelas selecionadas.

  2. Defina o par de chave-valor YOUR_VARIABLE e VALUE no bloco codeCompilationConfig de uma solicitação de compilação da API Dataform no formato a seguir:

    {
  "codeCompilationConfig": {
    "vars": {
      "YOUR_VARIABLE": "VALUE"
    }
  }
}

  3. Substitua YOUR_VARIABLE pelo nome da variável, por exemplo, executionSetting.

  4. Substitua VALUE pelo valor da variável para este resultado de compilação que atenda à condição when definida nas tabelas selecionadas.

O exemplo de código abaixo mostra a variável executionSetting transmitida a uma solicitação de compilação da API Dataform:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Executar um resultado de compilação com substituições

O exemplo de código abaixo mostra um ID de resultado de compilação transmitido em uma solicitação workflowInvocations.create:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Criar uma configuração de versão

As seções a seguir mostram como criar uma configuração de lançamento no Dataform para configurar 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, de preparo e de produção.

Para executar fluxos de trabalho 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 em um espaço de trabalho do Dataform.

As configurações de lançamento permitem personalizar os resultados da compilação. Eles podem ser usados para criar ambientes de execução, por exemplo, de pré-produção.

Configurações de lançamento

Em uma configuração de lançamento, é possível configurar substituições de compilação de 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
O ID da versão, o commitish do Git para resultados de compilação e a frequência de criação de resultados de compilação. A frequência é uma configuração opcional. Se definido, 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 versão 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 lançamento. Se definido, a frequência mínima é de 1 hora. É possível acionar a compilação manualmente na página Detalhes da configuração da versão ou acionar a compilação com o método releaseConfigs da API Dataform.

Durante a compilação, o Dataform extrai o código do commitish Git especificado do 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 de 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 de configurações de versão em configurações de fluxo de trabalho. Também é possível executar uma configuração de lançamento selecionada fora de qualquer programação. Durante a execução de 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.

Criar uma configuração de versão

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

  1. No repositório, acesse Lançamentos e programação.
  2. Na seção Configurações de lançamento, clique em Criar.

  3. No painel Criar configuração de 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 só podem incluir números, letras, hifens e sublinhados.

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

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

    3. Opcional: na lista Frequência, selecione a frequência de criação de resultados de compilação.

      Se definido, a frequência mínima é de uma hora.

  4. Opcional: na seção Substituições de compilação, configure 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 nas configurações do fluxo de trabalho.
    3. No campo Prefixo da tabela, insira um prefixo para todos os nomes de tabela.

  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, verifique se sua conta de serviço do Dataform tem acesso ao projeto definido na configuração da versão.

Por exemplo, a configuração de lançamento a seguir 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
  • Git commitish: main
  • Frequência: por hora
  • Nenhuma substituição de compilação

Conferir os detalhes de uma configuração de lançamento

É possível conferir 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 em tempo real
    • Carimbo de data/hora da criação
    • Commitish do Git
    • SHA de confirmação
  • Resultados de compilação anteriores

Para conferir os 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 lançamento.
  3. Na página Detalhes da configuração de lançamento, inspecione os detalhes da configuração de lançamento.

A tabela Resultados de compilação programada mostra os resultados de compilação anteriores criados automaticamente pela configuração de lançamento.

A tabela Resultados de compilação manual/da API mostra os resultados de compilação criados manualmente ou por chamadas à API Dataform dos 1.000 resultados de compilação mais recentes no repositório.

Acionar a compilação manualmente

Para criar manualmente um resultado de compilação de 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 lançamento.
  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 de compilação manual são mostrados na tabela Resultados de compilação manual/da 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 da versão, clique em Iniciar execução.
  3. No painel Executar fluxo de trabalho manual, na lista Configuração da versão, selecione uma configuração de versão.
  4. Selecione as ações do fluxo de trabalho a serem executadas:
    1. Para executar todo o fluxo de trabalho, clique em Todas as ações.
    2. Para executar as ações selecionadas no fluxo de trabalho, 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 as ações ou tags selecionadas e as dependências delas, selecione a opção Incluir dependências.

  7. Opcional: para recriar todas as tabelas do zero, selecione a opção Run with full refresh.

    Sem essa opção, o Dataform atualiza tabelas incrementais sem recriar do zero.

  8. Clique em Iniciar execução.

Editar uma configuração de versão

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

  1. No repositório, acesse Lançamentos e programação.
  2. Na configuração da 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 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 da 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