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

Este documento mostra 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 seu fluxo de trabalho SQL, o Dataform compila seu código em SQL para criar um resultado de compilação. Em seguida, durante uma invocação do fluxo de trabalho, o Dataform executa o resultado da compilação no BigQuery.

Por padrão, o Dataform usa as configurações no arquivo dataform.json para criar o resultado da compilação. Para isolar os dados executados em diferentes estágios do ciclo de vida de desenvolvimento, você pode substituir as configurações padrão com substituições de compilação.

Ao transmitir as solicitações da API Dataform no terminal, você pode criar e executar um único resultado de compilação com substituições. Você pode 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, você precisa gerar a solicitação compilationResults.create da API Dataform. Na solicitação, você precisa especificar uma fonte, um espaço de trabalho ou um commitish do Git, para que o Dataform compile no resultado da compilação. No objeto CodeCompilationConfig da solicitação compilationResults.create, é possível configurar substituições de compilação.

Em seguida, você pode executar o resultado de compilação criado em uma solicitação workflowInvocations.create da API Dataform.

Você pode configurar as seguintes substituições de compilação usando a API Dataform:

Projeto do Google Cloud
Projeto do Google Cloud em que o Dataform executa o resultado da compilação, definido em dataform.json como defaultDatabase.
Prefixo da tabela
Prefixo personalizado adicionado a todos os nomes de tabela no resultado da compilação.
Sufixo do esquema
Sufixo personalizado anexado ao esquema de tabelas definidas em defaultSchema em dataform.json ou no parâmetro schema no bloco config de uma tabela.
Valor de uma variável de compilação
Valor de uma variável de compilação a ser usada no resultado da compilação. Use variáveis de compilação para executar tabelas condicionalmente.

Como alternativa às substituições de compilação da API Dataform que só pode ser usada para um resultado de compilação, configure as substituições de compilação do espaço de trabalho no console do Google Cloud.

Para conhecer outras formas de configurar substituições de compilação no Dataform, consulte Introdução ao ciclo de vida do código.

Antes de começar

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

    Acesse o Dataform

  2. Selecione ou crie um repositório.

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

Definir uma origem do resultado da compilação

Para gerar a solicitação compilationResults.create da API Dataform, você precisa especificar uma origem para o resultado da compilação.

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

Definir um espaço de trabalho como origem do resultado da 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 pelo nome do projeto do Google Cloud;
  • LOCATION pelo local do repositório do Dataform, definido em dataform.json.
  • REPOSITORY_NAME pelo nome do repositório do Dataform.
  • WORKSPACE_NAME pelo nome do espaço de trabalho do Dataform.

O exemplo de código a seguir mostra a propriedade workspace na solicitação compilationResults.create definida como 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 fonte de resultado de compilação

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

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

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

{
  "gitCommitish": "staging"
}

Substituir o projeto padrão do Google Cloud

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

Transmitir um ID de projeto padrão separado na solicitação compilationResults.create modifica o ID do projeto padrão do Google Cloud configurado no arquivo dataform.json, mas não substitui os IDs de projeto do Google Cloud configurados em tabelas individuais.

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

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

Substitua PROJECT_NAME pelo ID do projeto do Google Cloud 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. Basta transmitir 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 sufixo que você quer anexar, por exemplo, _staging. Por exemplo, se a defaultSchema em dataform.json estiver definida como dataform, o Dataform vai criar tabelas no esquema dataform_staging.

Anexar um sufixo de esquema

Para separar os dados de desenvolvimento, preparo e produção, é possível anexar um sufixo aos 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 defaultSchema em dataform.json estiver definida como dataform, o Dataform vai criar tabelas no esquema dataform_staging.

Observação:o parâmetro CodeCompilationConfig schemaSuffix substitui os esquemas configurados no bloco config de arquivos individuais.

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

Para executar uma tabela selecionada somente 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 seguinte formato:

    {
 "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 esse resultado de compilação que atende à condição when definida nas tabelas selecionadas.

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

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

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

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"
}

A seguir