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 o 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 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, 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, 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 Google Cloud: Google Cloud projeto em que o Dataform executa o resultado da compilação, definido em workflow_settings.yaml como defaultProject ou 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 definido em defaultDataset em workflow_settings.yaml, defaultSchema em dataform.json ou no parâmetro schema no 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.

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.

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, uma tag ou um 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 pelo nome do Google Cloud projeto.
  • LOCATION com o local do repositório do Dataform, definido nas configurações do fluxo de trabalho.
  • REPOSITORY_NAME pelo nome do repositório do Dataform.
  • WORKSPACE_NAME pelo 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 selecionado no seguinte formato:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Substitua GIT_COMMITISH pelo branch ou tag do Git selecionado 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 Google Cloud padrão

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

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

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

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

Substitua PROJECT_NAME pelo ID do projeto 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 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 sufixo que você quer anexar, por exemplo, _staging. Por exemplo, se o defaultDataset em workflow_settings.yaml estiver definido como dataform, o Dataform vai criar tabelas no esquema dataform_staging.

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 o defaultDataset em workflow_settings.yaml estiver definido como dataform, o Dataform vai criar tabelas no esquema dataform_staging.

Observação:o parâmetro schemaSuffix CodeCompilationConfig 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 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-a à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 atende à 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 a seguir 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