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 uma compilação resultado. Então, durante um fluxo de trabalho invocação, O Dataform executa o resultado da compilação no BigQuery.

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

Ao transmitir solicitações da API Dataform no terminal, você pode criar e executar uma resultado único de uma compilação com substituições de compilação. É possível criar um resultado da 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, é necessário aumentar o API Dataform compilationResults.create solicitação. Na solicitação, você precisa especificar uma origem, um workspace ou Gitish do Git, para que o Dataform seja compilado no com base no resultado da compilação. Na CodeCompilationConfig objeto da solicitação compilationResults.create, é possível configurar a compilação substituições.

Você pode executar o resultado da compilação criada em uma API Dataform workflowInvocations.create solicitação.

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

Google Cloud projeto : Projeto do Google Cloud em que o Dataform executa Resultado da compilação, definido em workflow_settings.yaml como defaultProject ou em dataform.json como defaultDatabase.

Prefixo da tabela
O prefixo personalizado foi adicionado a todos os nomes de tabela da o resultado da compilação.
Sufixo do esquema
Sufixo personalizado anexado ao esquema das tabelas definido em defaultDataset no workflow_settings.yaml, defaultSchema em dataform.json ou na schema no bloco config de uma tabela.

O valor de uma compilação variável : Valor de uma variável de compilação a ser usada no resultado da compilação. Você podem 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 espaço de trabalho no console do Google Cloud.

Para aprender sobre formas alternativas de configurar substituições de compilação na o Dataform, consulte Introdução ao código de desenvolvimento de software.

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 do resultado de compilação

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

Você pode definir um espaço de trabalho do Dataform ou uma ramificação do Git, uma tag do Git ou um Git confirmar o SHA como a origem na compilationResults.create solicitação.

Definir um espaço de trabalho como origem do resultado de compilação

  • Na compilationResults.create solicitação, preencha a propriedade workspace com o caminho de uma solicitação Espaço de trabalho 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 nas configurações de fluxo de trabalho.
  • REPOSITORY_NAME pelo nome do Dataform repositório de dados.
  • 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 origem de resultado de compilação

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

Substitua GIT_COMMITISH pela ramificação do Git selecionada, uma tag do Git ou uma tag do Git confirmar o SHA 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 usado para desenvolvimento, é possível transmitir outro projeto do Google Cloud na CodeCompilationConfig Objeto na API Dataform compilationResults.create solicitação.

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

  • Para substituir o ID do projeto padrão do Google Cloud, defina o defaultDatabase para o ID do projeto do Google Cloud selecionado na Objeto CodeCompilationConfig no seguinte formato:

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

Substitua PROJECT_NAME pelo ID do projeto do Google Cloud que você quer. a ser definido para o resultado da compilação.

Adicionar um prefixo de tabela

Para identificar rapidamente as tabelas no resultado da compilação, você pode adicionar um prefixo ao todos os nomes de tabelas no resultado da compilação passando o prefixo da tabela na CodeCompilationConfig Objeto na API Dataform compilationResults.create solicitação.

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

Anexar um sufixo de esquema

Para separar os dados de desenvolvimento, preparo e produção, anexe um sufixo a esquemas em um resultado de compilação passando o sufixo do esquema na CodeCompilationConfig Objeto na API Dataform compilationResults.create solicitação.

  • Para anexar um sufixo de esquema, defina a propriedade schemaSuffix na Objeto CodeCompilationConfig no seguinte formato:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Substitua SUFFIX pelo sufixo que você quer anexar, por exemplo: _staging. Por exemplo, se defaultDataset em workflow_settings.yaml for definido como dataform, o Dataform vai criar tabelas dataform_staging.

Observação:o schemaSuffix de CodeCompilationConfig o parâmetro 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, é possível criar uma variável de compilação para a configuração de execução e, em seguida, passe seu valor no campo CodeCompilationConfig Objeto na API Dataform compilationResults.create solicitação.

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

  1. Criar uma variável de compilação e adicioná-la aos ícones tabelas.

  2. Defina o par de chave-valor YOUR_VARIABLE e VALUE no Bloco codeCompilationConfig de um Solicitação de compilação da API Dataform no 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 esta compilação. resultado que cumpre a condição when definida nos itens selecionados do BigQuery.

O exemplo de código a seguir mostra a variável executionSetting transmitida para um 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 a seguir mostra um ID de resultado de compilação transmitido em uma workflowInvocations.create solicitação:

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

A seguir