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 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 por 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. 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 com substituições de compilação, você precisa gerar a
solicitação
compilationResults.create
da API
Dataform. Na solicitação, você precisa especificar uma origem, 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, você pode executar o resultado da 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 workflow_settings.yaml
como defaultProject
ou em dataform.json
como defaultDatabase
.
- Prefixo da tabela
- Prefixo personalizado adicionado a todos os nomes de tabelas no resultado da compilação.
- Sufixo do esquema
- Sufixo personalizado anexado ao esquema de tabelas
definidos em
defaultDataset
emworkflow_settings.yaml
,defaultSchema
emdataform.json
ou no parâmetroschema
no blococonfig
de uma tabela.
Valor de uma variável de compilaçã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 em um resultado de compilação, configure substituições de compilação do espaço de trabalho no console do Google Cloud.
Para saber mais sobre formas alternativas de configurar substituições de compilação no Dataform, consulte Introdução ao ciclo de vida do código.
Antes de começar
No Console do Google Cloud, acesse a página Dataform.
Selecione ou crie um repositório.
Selecione ou crie um espaço de trabalho de desenvolvimento.
Definir uma origem do resultado de 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 origem na solicitação compilationResults.create
.
Definir um espaço de trabalho como origem do resultado de compilação
- Na solicitação
compilationResults.create
, preencha a propriedadeworkspace
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 nas configurações do fluxo de trabalho.
- 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 origem de resultado de compilação
Na solicitação
compilationResults.create
, preencha a propriedadegitCommitish
com a ramificação, a tag ou o SHA de confirmação selecionado no formato a seguir:{ "gitCommitish": "GIT_COMMITISH" }
Substitua GIT_COMMITISH pela ramificação do Git selecionada, uma tag do Git ou 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, é possível transmitir um ID do 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 de configurações do fluxo de trabalho, 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 objetoCodeCompilationConfig
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 tabelas 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 objetoCodeCompilationConfig
com este formato:
{
"codeCompilationConfig": {
"tablePrefix": "PREFIX",
}
}
Substitua PREFIX pelo sufixo que você quer anexar, por exemplo,
_staging
. Por exemplo, se 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 os dados de desenvolvimento, preparo e produção, anexe 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 objetoCodeCompilationConfig
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
estiver definido 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 essa configuraçã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:
- Crie uma variável de compilação e a adicione às tabelas selecionadas.
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 abaixo:{ "codeCompilationConfig": { "vars": { "YOUR_VARIABLE": "VALUE" } } }
Substitua YOUR_VARIABLE pelo nome da sua variável, por exemplo,
executionSetting
.Substitua VALUE pelo valor da variável desse 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 substituições de compilação
- Para executar o resultado da compilação criado por uma solicitação
compilationResults.create
, transmita o ID do resultado de compilação retornado pela solicitaçãocompilationResults.create
em uma solicitaçãoworkflowInvocations.create
.
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
- Para saber mais sobre maneiras de configurar substituições de compilação no Dataform, consulte Introdução ao ciclo de vida do código.
- Para saber mais sobre a API Dataform, consulte API Dataform.
- Para saber como usar o console do Google Cloud para configurar substituições de compilação para todos os espaços de trabalho em um repositório, consulte Configurar substituições de compilação do espaço de trabalho.