Configure compilações

Este documento mostra como fazer o seguinte no Dataform:

Antes de começar

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Selecione ou crie um repositório.

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

  4. Opcional: para substituir o projeto Google Cloud predefinido na configuração de lançamento, conceda acesso ao agente do serviço Dataform ou à conta de serviço personalizada ao projeto que planeia usar.

Funções necessárias

Para receber as autorizações de que precisa para concluir as tarefas neste documento, peça ao seu administrador para lhe conceder a função de IAM Administrador do Dataform (roles/dataform.admin) nos repositórios. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Para melhorar a segurança do agendamento, consulte o artigo Implemente autorizações de agendamento melhoradas.

Para poder atualizar a versão de lançamento de uma configuração de lançamento para um repositório do Dataform, tem de conceder a autorização iam.serviceAccounts.actAs ao agente do serviço do Dataform para cada conta de serviço personalizada nas configurações do fluxo de trabalho que estão a usar esta configuração de lançamento. Esta autorização está disponível na função de utilizador da conta de serviço (roles/iam.serviceAccountUser). Para mais informações, consulte o artigo Conceda a função de utilizador da conta de serviço do IAM.

Introdução ao ciclo de vida do fluxo de trabalho no Dataform

Esta secção descreve o ciclo de vida do fluxo de trabalho no Dataform e as formas de configurar a compilação e a execução no Dataform.

O ciclo de vida do fluxo de trabalho do Dataform consiste nas seguintes fases:

Programação
Desenvolve um fluxo de trabalho num espaço de trabalho do Dataform.
Compilação

O Dataform compila o código do fluxo de trabalho no seu espaço de trabalho para SQL em tempo real, criando um resultado da compilação do espaço de trabalho que pode executar no BigQuery. O Dataform usa as definições que define no ficheiro de definições do fluxo de trabalho para criar o resultado da compilação.

A compilação do Dataform é hermética para garantir a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação de SQL sempre. O Dataform compila o seu código num ambiente de sandbox sem acesso à Internet. Não estão disponíveis ações adicionais, como chamar APIs externas, durante a compilação.

Execução

Numa invocação do fluxo de trabalho, o Dataform executa o resultado da compilação do espaço de trabalho no BigQuery.

Para personalizar o ciclo de vida do fluxo de trabalho do Dataform de acordo com as suas necessidades, pode configurar o resultado da compilação para influenciar onde e como o Dataform executa o seu fluxo de trabalho. Em seguida, pode acionar ou agendar manualmente execuções para influenciar o momento em que o Dataform executa todo o fluxo de trabalho ou os respetivos elementos selecionados.

Formas de configurar a compilação do Dataform

Por predefinição, o Dataform usa as definições no ficheiro de definições do fluxo de trabalho para criar resultados de compilação. Pode substituir as predefinições com substituições de compilação para criar resultados de compilação personalizados. Em seguida, pode acionar manualmente uma execução de um resultado de compilação personalizado ou agendar execuções.

O Dataform oferece as seguintes opções para configurar os resultados da compilação:

Substituições de compilação do Workspace
Pode configurar substituições de compilação que se aplicam a todos os espaços de trabalho num repositório. Pode usar substituições de compilação do espaço de trabalho para criar ambientes de desenvolvimento isolados.
Configurações de lançamento
Pode criar configurações de lançamento para configurar modelos para criar resultados de compilação de um repositório do Dataform. Em seguida, pode criar uma configuração do fluxo de trabalho para agendar execuções de resultados de compilação criados numa configuração de lançamento selecionada.
Substituições de compilação da API Dataform
Pode transmitir pedidos da API Dataform no terminal para criar e executar um único resultado de compilação com substituições de compilação.

Configure substituições de compilação do espaço de trabalho

Com as substituições de compilação do espaço de trabalho, pode criar substituições de compilação para todos os espaços de trabalho num repositório do Dataform. Pode criar uma configuração de substituições de compilação do espaço de trabalho para cada repositório.

Quando aciona manualmente uma execução num espaço de trabalho num repositório com substituições de compilação do espaço de trabalho, o Dataform aplica estas substituições ao resultado da compilação do espaço de trabalho.

Pode configurar as seguintes substituições de compilação do espaço de trabalho:

  • Google Cloud projeto no qual o Dataform executa os conteúdos do espaço de trabalho
  • Prefixo da tabela
  • Sufixo do esquema

Pode usar substituições de compilação do espaço de trabalho para criar ambientes de desenvolvimento isolados, isolando os resultados da compilação do espaço de trabalho no BigQuery com substituições de compilação dinâmicas. A compilação do prefixo da tabela dinâmica e do sufixo do esquema contém a variável ${workspaceName}. Quando aciona uma execução num espaço de trabalho, o Dataform substitui a variável ${workspaceName} pelo nome do espaço de trabalho atual, criando substituições de compilação exclusivas do espaço de trabalho.

Tenha em atenção que não pode agendar execuções de resultados de compilação criados com substituições de compilação do espaço de trabalho.

Crie configurações de lançamentos

Com as configurações de lançamento, pode configurar modelos de definições para criar resultados de compilação de repositórios.

Numa configuração de lançamento, pode configurar substituições de compilação das definições do fluxo de trabalho, das variáveis de compilação e da frequência de criação de resultados de compilação de todo o repositório.

Numa configuração de lançamento, pode configurar as seguintes substituições de compilação:

Pode criar várias configurações de lançamento num repositório do Dataform, uma para cada fase do ciclo de vida de desenvolvimento, criando resultados de compilação do repositório isolados.

Em seguida, pode criar configurações de fluxo de trabalho para agendar execuções de resultados de compilação criados numa configuração de lançamento selecionada.

Também pode acionar manualmente a execução de um resultado da compilação numa configuração de lançamento selecionada.

Configure um único resultado de compilação com substituições de compilação da API Dataform

Ao transmitir pedidos da API Dataform no terminal, pode configurar substituições de compilação para um único resultado de compilação.

No pedido compilationResults.create, pode criar um único resultado de compilação de um espaço de trabalho do Dataform ou de um comittish do Git especificado.

No objeto CodeCompilationConfig do pedido compilationResults.create, pode configurar substituições de compilação para o pedido de compilação.

Pode configurar as seguintes substituições de compilação da API Dataform:

Tenha em atenção que as substituições de compilação da API Dataform aplicam-se a um único resultado de compilação e a uma única execução. Não pode usá-las para agendar execuções do Dataform.

Pode executar um resultado de compilação no pedido workflowInvocations.create.

Formas de configurar a execução do Dataform

O Dataform oferece as seguintes opções para configurar a execução:

Execução manual num espaço de trabalho
Pode acionar manualmente a execução instantânea de um fluxo de trabalho num espaço de trabalho do Dataform, fora de qualquer programação. Pode executar ações selecionadas no fluxo de trabalho.
Configurações do fluxo de trabalho
Pode agendar execuções de resultados de compilação criados numa configuração de lançamento selecionada. Pode selecionar as ações do fluxo de trabalho a executar e definir a frequência e o fuso horário das execuções.

Acione a execução instantânea num espaço de trabalho

Num espaço de trabalho do Dataform, pode acionar manualmente a execução instantânea de um fluxo de trabalho no seu espaço de trabalho, fora de qualquer programação.

Pode executar manualmente os seguintes elementos do fluxo de trabalho no seu espaço de trabalho:

Se o seu repositório contiver substituições de compilação do espaço de trabalho, pode ver que substituições de compilação o Dataform vai aplicar ao resultado da compilação do espaço de trabalho.

Crie configurações de fluxos de trabalho

Com as configurações do fluxo de trabalho, pode agendar execuções de resultados de compilação a partir de uma configuração de lançamento selecionada. Pode criar várias configurações de fluxo de trabalho num repositório do Dataform.

Numa configuração do fluxo de trabalho, pode configurar as seguintes definições de execução:

  • Configuração de lançamento de compilação aplicada.
  • Seleção das ações do fluxo de trabalho a executar.
  • Programação e fuso horário das execuções.

Pode selecionar as seguintes ações do fluxo de trabalho a executar:

  • Todas as ações
  • Ações selecionadas
  • Ações com etiquetas selecionadas

Em seguida, durante uma execução agendada da configuração do fluxo de trabalho, o Dataform implementa a sua seleção de ações a partir do resultado da compilação aplicado no BigQuery.

As configurações de lançamento e as configurações de fluxo de trabalho do Dataform permitem-lhe configurar a compilação e agendar execuções no Dataform, sem ter de depender de serviços adicionais.

Expiração dos recursos do ciclo de vida

O Dataform armazena os resultados da compilação e as invocações do fluxo de trabalho durante um período específico.

Validade das invocações de fluxos de trabalho

As invocações do fluxo de trabalho expiram após 90 dias ou quando as elimina manualmente.

Numa configuração do fluxo de trabalho, pode ver uma lista das invocações do fluxo de trabalho mais recentes criadas pela configuração. Quando uma invocação de fluxo de trabalho criada por uma configuração de fluxo de trabalho expira, o Dataform remove essa invocação de fluxo de trabalho da lista de invocações recentes.

Expiração dos resultados da compilação

A expiração dos resultados da compilação depende de terem sido criados num espaço de trabalho de desenvolvimento, numa configuração de lançamento ou por uma invocação do fluxo de trabalho.

Quando desenvolve um fluxo de trabalho num espaço de trabalho do Dataform, o Dataform compila o seu código num resultado de compilação em tempo real para fornecer validação de consultas. Os resultados da compilação criados desta forma expiram após 24 horas.

Numa configuração de lançamento, o resultado da compilação mais recente torna-se o resultado da compilação em direto. Um novo resultado de compilação substitui o resultado de compilação em direto atual. O Dataform retém o resultado da compilação em direto até ser substituído por um novo resultado da compilação. Um resultado de compilação substituído expira no prazo de 24 horas.

O Dataform remove os resultados de compilação expirados da lista de resultados de compilação anteriores na página Detalhes de uma configuração de lançamento.

O Dataform retém os resultados da compilação criados por invocações de fluxo de trabalho durante todo o ciclo de vida da invocação de fluxo de trabalho, até 24 horas após a expiração ou a eliminação da invocação de fluxo de trabalho.

Crie substituições de compilação do espaço de trabalho

As secções seguintes mostram como criar substituições de compilação do espaço de trabalho para isolar tabelas e visualizações criadas a partir dos seus espaços de trabalho do Dataform no BigQuery. Pode usar substituições de compilação do espaço de trabalho para criar ambientes de desenvolvimento do Dataform isolados.

Quando desenvolve código de fluxo de trabalho num espaço de trabalho do Dataform, o Dataform compila o código no seu espaço de trabalho em tempo real para criar um resultado da compilação do espaço de trabalho. O Dataform usa as definições definidas no ficheiro de definições do fluxo de trabalho para criar o resultado da compilação do espaço de trabalho. Em seguida, quando aciona a execução num espaço de trabalho, o Dataform executa o resultado da compilação do espaço de trabalho no BigQuery.

Para substituir as predefinições definidas nas definições do fluxo de trabalho para todos os espaços de trabalho no seu repositório, pode criar substituições de compilação do espaço de trabalho.

Com as substituições de compilação do espaço de trabalho, pode substituir as seguintes definições para todos os espaços de trabalho no seu repositório:

Projeto

O Google Cloud projeto no qual o Dataform executa o resultado da compilação do espaço de trabalho, definido em workflow_settings.yaml como defaultProject ou em dataform.json como defaultDatabase.

Prefixo da tabela

O prefixo personalizado adicionado a todos os nomes das tabelas em todos os espaços de trabalho no repositório.

Sufixo do esquema

O sufixo personalizado anexado ao esquema das tabelas. Defina como defaultDataset em workflow_settings.yaml, defaultSchema em dataform.json ou no parâmetro schema no bloco config de uma tabela.

Para criar ambientes de desenvolvimento isolados, pode isolar espaços de trabalho com substituições de compilação únicas. Pode modificar dinamicamente os prefixos das tabelas e as substituições de compilação de sufixos de esquemas com a variável ${workspaceName}.

Quando aciona manualmente a execução num espaço de trabalho, a variável ${workspaceName} injeta o nome do espaço de trabalho nas substituições da compilação do espaço de trabalho.

Quando define ${workspaceName} como o prefixo da tabela, o Dataform adiciona o nome do espaço de trabalho aos nomes de todas as tabelas no espaço de trabalho. Após a execução, no BigQuery, pode identificar o espaço de trabalho de origem de uma tabela.

Quando define ${workspaceName} como o sufixo do esquema, o Dataform anexa o nome do espaço de trabalho a defaultSchema, criando um esquema personalizado dedicado ao espaço de trabalho. Após a execução, no BigQuery, pode localizar todas as tabelas executadas a partir de um espaço de trabalho específico no esquema dedicado.

Exemplo de substituições de compilação do espaço de trabalho dinâmico

O exemplo seguinte mostra substituições de compilação do espaço de trabalho dinâmico aplicadas a um repositório que contém espaços de trabalho com os nomes dos programadores que trabalham no repositório: Sasha e Kai.

O objetivo das substituições de compilação do espaço de trabalho neste exemplo é criar ambientes de desenvolvimento isolados para a Sasha e o Kai.

As seguintes definições predefinidas estão definidas em workflow_settings.yaml:

  • defaultProject : analytics
  • defaultDataset: dataform

As seguintes substituições de compilação do espaço de trabalho criam um prefixo da tabela dinâmico e um sufixo do esquema para cada espaço de trabalho no repositório:

  • ID do projeto do Google Cloud: analytics_dev
  • Prefixo da tabela: ${workspaceName}
  • Sufixo do esquema: ${workspaceName}

Quando a Sara aciona manualmente a execução no espaço de trabalho do Sasha, o Dataform executa o respetivo conteúdo com as seguintes definições:

  • Google Cloud project: analytics_dev
  • Esquema: dataform_sasha
  • Nomes das tabelas: sasha_name, por exemplo, sasha_orders

Quando o Kai aciona manualmente a execução no espaço de trabalho do Kai, o Dataform executa o respetivo conteúdo com as seguintes definições:

  • Google Cloud project: analytics_dev
  • Esquema: dataform_kai
  • Nomes das tabelas: kai_name, por exemplo, kai_orders

Crie substituições de compilação do espaço de trabalho

Para criar substituições de compilação do espaço de trabalho do Dataform, siga estes passos:

  1. No repositório, aceda a Definições.
  2. Clique em Edit.
  3. No painel Substituições de compilação do Workspace, no campo ID do projeto do Google Cloud, introduza o ID do projeto.
  4. No campo Prefixo da tabela, introduza um prefixo para todos os nomes das tabelas.
    1. Opcional: para criar um prefixo de tabela dinâmico que seja único para cada espaço de trabalho, introduza ${workspaceName} como prefixo de tabela.
  5. No campo Sufixo do esquema, introduza um sufixo a anexar ao esquema da tabela ou vista criada.
    1. Opcional: para criar um sufixo do esquema dinâmico que seja único para cada espaço de trabalho, introduza ${workspaceName} como sufixo da tabela.
  6. Clique em Guardar.

O Dataform aplica substituições de compilação do espaço de trabalho a todos os espaços de trabalho no seu repositório.

Edite substituições de compilação do espaço de trabalho

Para editar substituições de compilação do espaço de trabalho do Dataform, siga estes passos:

  1. No repositório, aceda a Definições.
  2. Clique em Edit.
  3. Edite as substituições de compilação do espaço de trabalho e, de seguida, clique em Guardar.

Elimine as substituições de compilação do espaço de trabalho

Para eliminar substituições de compilação do espaço de trabalho do Dataform, siga estes passos:

  1. No repositório, aceda a Definições.
  2. Clique em Edit.
  3. No painel Substituições de compilação do espaço de trabalho, clique em Limpar tudo e, de seguida, clique em Guardar.

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

Esta secção mostra como criar e executar um resultado de compilação com substituições de compilação através da API Dataform.

Acerca das substituições de compilação da API Dataform

Para executar o fluxo de trabalho, o Dataform compila o seu código em SQL para criar um resultado da compilação. Em seguida, durante uma invocação do fluxo de trabalho, o Dataform executa o resultado da compilação no BigQuery.

Por predefinição, o Dataform usa as definições no ficheiro de definições do fluxo de trabalho para criar o resultado da compilação. Para isolar os dados executados em diferentes fases do ciclo de vida de desenvolvimento, pode substituir as predefinições com substituições de compilação.

Ao transmitir pedidos da API Dataform no terminal, pode criar e executar um único resultado de compilação com substituições de compilação. 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 de compilação, tem de aumentar o pedido da API Dataform compilationResults.create. No pedido, tem de especificar uma origem, que deve ser um espaço de trabalho ou um commitish do Git, para o Dataform compilar no resultado da compilação. No CodeCompilationConfig objeto do pedido compilationResults.create, pode configurar substituições de compilação.

Em seguida, pode executar o resultado da compilação criado num pedido workflowInvocations.create> da API Dataform.

Pode configurar as seguintes substituições de compilação através da API Dataform:

Google Cloud projeto

O projeto no qual o Dataform executa o resultado da compilação, definido no ficheiro workflow_settings.yaml como a propriedade defaultProject ou no ficheiro dataform.json como a propriedade defaultDatabase.

Prefixo da tabela

O prefixo personalizado adicionado a todos os nomes das tabelas no resultado da compilação.

Sufixo do esquema

O sufixo personalizado anexado ao esquema das tabelas definidas na propriedade defaultDataset no ficheiro workflow_settings.yaml, na propriedade defaultSchema no ficheiro 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 usar no resultado da compilação. Pode usar variáveis de compilação para executar tabelas condicionalmente.

Em alternativa às substituições de compilação da API Dataform, que só pode usar para um resultado de compilação, pode configurar substituições de compilação do espaço de trabalho na Google Cloud consola.

Para saber mais sobre formas alternativas de configurar substituições de compilação no Dataform, consulte o artigo Introdução ao ciclo de vida do fluxo de trabalho no Dataform.

Defina uma origem de resultados de compilação

Para aumentar o pedido da API Dataform compilationResults.create, tem de especificar uma origem para o resultado da compilação.

Pode definir um espaço de trabalho do Dataform ou um ramo Git, uma etiqueta Git ou um SHA de commit Git como a origem no pedido compilationResults.create.

Defina um espaço de trabalho como uma origem de resultados de compilação

  • No pedido 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 o seguinte:

    • PROJECT_NAME: o nome do seu projeto Google Cloud .
    • LOCATION: a localização do seu repositório do Dataform, definida nas definições do fluxo de trabalho.
    • REPOSITORY_NAME: o nome do seu repositório do Dataform.
    • WORKSPACE_NAME: o nome do seu espaço de trabalho do Dataform.

O seguinte exemplo de código mostra a propriedade workspace no pedido compilationResults.create definida para um espaço de trabalho denominado "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Defina um commitish do Git como uma origem do resultado da compilação

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

    Substitua GIT_COMMITISH pelo ramo Git selecionado, pela etiqueta Git ou por um SHA de consolidação do Git para o resultado da compilação.

O seguinte exemplo de código mostra a propriedade gitCommitish no pedido compilationResults.create definida como "staging":

{
  "gitCommitish": "staging"
}

Substitua o projeto predefinido

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

A transmissão de um ID do projeto predefinido separado no pedido compilationResults.create substitui o ID do projeto predefinido configurado no ficheiro de definições do fluxo de trabalho, mas não substitui os IDs do projeto configurados em tabelas individuais.

  • Para substituir o ID do projeto predefinido, defina a propriedade defaultDatabase para o ID do projeto selecionado no objeto CodeCompilationConfig no seguinte formato:

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

    Substitua PROJECT_NAME pelo ID do projeto que quer definir para o resultado da compilação.