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

Este documento mostra como criar e executar um resultado de compilação com modificações de compilação usando a API Dataform.

Sobre 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 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 do desenvolvimento, modifique as configurações padrão com modificaçõ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 modificações de compilação. É possível criar um resultado de compilação de um espaço de trabalho ou de um commit do Git selecionado.

Para criar um resultado de compilação com modificações de compilação, 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 commit 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 da compilação em uma solicitação da API Dataform workflowInvocations.create

Você pode configurar as seguintes modificaçõ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 das 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. Você pode usar variáveis de compilação para executar tabelas condicionalmente.

Como alternativa às substituições de compilação da API Dataform, que você só pode usar para um resultado de compilação, é possível configurar substituições de compilação do espaço de trabalho no Console do Google Cloud.

Antes de começar

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

    Acessar o Dataform

  2. Selecione ou crie um repositório.

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

Definir uma fonte de resultados de compilação

Para gerar a solicitação compilationResults.create da API Dataform, especifique 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 commit do Git como a origem na solicitação compilationResults.create.

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

  • Na solicitação compilationResults.create, preencha a propriedade workspace com o caminho de um espaço de trabalho selecionado do Dataform 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.

A 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 commit do Git como uma fonte de resultados de compilação

  • Na solicitação compilationResults.create, preencha a propriedade gitCommitish com o branch, a tag ou o commit SHA desejados do Git no seguinte formato:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Substitua GIT_COMMITISH pelo branch do Git, pela tag do Git ou por um SHA de commit do Git para o resultado da compilação.

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

{
  "gitCommitish": "staging"
}

Modificar 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 do 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 modifica o ID do projeto padrão do Google Cloud configurado no arquivo dataform.json, mas não 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 desejado 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 tabelas facilmente no resultado da compilação, é possível adicionar 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 defaultSchema em dataform.json estiver definido como dataform, o Dataform 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 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 defaultSchema em dataform.json estiver definido como dataform, o Dataform 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, você pode criar uma variável de compilação para a configuração de execução e, em seguida, transmitir 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 a 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 sua 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 a seguir 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 modificações de compilação

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