Criar uma macro

Uma macro é um fluxo de trabalho avançado (DAG) reutilizável com um contrato declarado de entrada e saída. Você chama uma macro a partir de outro fluxo de trabalho com uma etapa Macro Run ou etapa Macro Concurrent — cada chamada é executada em seu próprio esquema de rascunho isolado, de modo que a mesma macro pode ser chamada simultaneamente por vários fluxos de trabalho pai ou por várias linhas de direcionamento sem que as execuções colidam.

Use uma macro quando tiver uma transformação de dados repetível e parametrizada — por exemplo, “processar um mês de dados de vendas de uma região” — que você queira chamar a partir de um fluxo de trabalho de direcionamento uma vez por mês, por região ou ambos. O chamador vincula tabelas e variáveis às portas de entrada declaradas da macro; ao terminar, as tabelas de saída declaradas são copiadas de volta para os destinos do lado do chamador.

Etapas

Abra o projeto que contém o fluxo de trabalho que você quer transformar em uma macro.
Mude para a guia Fluxos de trabalho e selecione a linha do fluxo de trabalho.
No painel Detalhes do fluxo de trabalho, à direita, confirme que o Tipo de fluxo de trabalho é Avançado. Se for padrão, use primeiro a ação Converter em avançado.
Na seção Macro do painel Detalhes do fluxo de trabalho, clique em Converter em macro… e confirme na caixa de diálogo. O fluxo de trabalho passa para o modo macro e um editor de portas aparece.
Clique em Adicionar porta para declarar cada entrada ou saída que a macro aceita ou produz. Para cada porta:
- Nome — um identificador curto que o chamador usa para vincular a esta porta (por exemplo, month, region_sales).
- Direção — Entrada (o chamador fornece este valor ou tabela) ou Saída (a macro produz isto e o chamador o recebe).
- Tipo — Tabela para uma tabela de dados, Escalar para um único valor (string / int / float / bool / date) ou Dimensão para uma referência a uma dimensão hierárquica.
- Obrigatório — desmarque se a macro puder ser executada sem que esta porta seja vinculada.
- Memorando — uma breve observação sobre o que esta porta representa, exibida aos autores no formulário de vinculação do lado do chamador.
Clique em Salvar portas.

O fluxo de trabalho agora é uma macro. Os autores que adicionarem uma etapa Macro Run em outro fluxo de trabalho verão as portas que você declarou e se vincularão a elas pelo nome.

Cada porta é um espaço nomeado e tipado no contrato da macro. Os chamadores se vinculam às portas pelo nome — as entradas são copiadas para dentro e as saídas são copiadas de volta para fora.

Chamar uma macro

No fluxo de trabalho chamador:

Adicione uma etapa Macro: Executar.
Em Macro a executar, selecione o projeto e o fluxo de trabalho da macro.
Vínculos de entrada — para cada porta de entrada que a macro declara, adicione uma vinculação:
- As portas de Tabela recebem uma tabela de origem do lado do chamador; opcionalmente, selecione um subconjunto de colunas e adicione um filtro (uma cláusula WHERE que referencia as variáveis de entrada escalares da macro) para que apenas a fatia necessária seja materializada no esquema de execução da macro.
- As portas Escalar / Dimensão recebem um valor (frequentemente uma variável de fluxo de trabalho do chamador) — definido ANTES da cópia de entrada das tabelas, para que o filtro da tabela de entrada possa referenciá-lo.
Vínculos de saída — para cada porta de saída que a macro produz, aponte para uma tabela de destino do lado do chamador (criada na hora se ainda não existir).
Salve a etapa.

Quando o fluxo de trabalho pai é executado e chega à etapa Macro Run, o executor:

Gera um novo run_id para esta chamada da macro.
Cria um esquema de rascunho por execução (macrorun_<run_id>) no catálogo do projeto.
Copia as tabelas de entrada vinculadas para o esquema de rascunho (a projeção de colunas e o filtro são aplicados na cópia de entrada, de modo que o filtro seja empurrado para a origem).
Define as variáveis de entrada escalares / de dimensão vinculadas na camada de variáveis com escopo de execução da macro.
Executa as etapas da macro no mesmo processo. Toda etapa SQL dentro da macro lê e grava no esquema de rascunho, e não no esquema do projeto.
Copia as tabelas de saída declaradas de volta para os destinos do chamador.
Descarta o esquema de rascunho (sempre — mesmo que uma etapa dentro da macro tenha falhado).

Cada chamada recebe um novo run_id e seu próprio esquema de rascunho. As etapas leem e gravam apenas nesse esquema, que é descartado quando a execução termina — com sucesso, erro ou interrupção.

Como cada chamada tem seu próprio esquema de rascunho, duas chamadas simultâneas à mesma macro (de um loop, de uma distribuição em paralelo ou de fluxos de trabalho independentes) nunca colidem nos nomes das tabelas intermediárias.

Executar uma macro por linha de direcionamento

Use Macro: Execução simultânea quando uma tabela do chamador deve conduzir várias chamadas independentes da macro.

Adicione uma etapa Macro: Execução simultânea.
Em Direcionador, selecione a tabela de direcionamento do lado do chamador e defina Execuções simultâneas como o número máximo de chamadas filhas da macro a executar ao mesmo tempo.
Em Seleção de dados da tabela, mapeie as colunas da tabela de direcionamento de que cada chamada filha precisa.
Em Filtro do direcionador, restrinja opcionalmente as linhas de direcionamento a processar.
Em Macro, selecione o fluxo de trabalho da macro.
Em Vínculos de entrada, vincule os valores das colunas do direcionador a variáveis escalares ou de dimensão da macro e vincule tabelas do lado do chamador a portas de tabela da macro.
Em Vínculos de saída, mapeie as portas de saída da macro para tabelas de destino do lado do chamador.

Cada linha de direcionamento selecionada recebe um run_id e um esquema de rascunho separados. Interromper a etapa pai interrompe todas as chamadas filhas ativas e descarta seus esquemas de execução.

Uma chamada por linha de direcionamento, cada uma em seu próprio esquema de rascunho — assim as tabelas intermediárias nunca colidem. Execuções simultâneas define quantas são executadas ao mesmo tempo, e cada linha grava sua própria tabela results_{region}.

Rebaixar uma macro

Você pode limpar o indicador de macro a qualquer momento clicando em Rebaixar para avançado… no painel Detalhes do fluxo de trabalho. O fluxo de trabalho volta a ser um fluxo de trabalho avançado comum, e qualquer etapa Macro Run do lado do chamador que o referencie falhará em tempo de execução com o erro “não é uma macro”. As portas declaradas permanecem no registro, de modo que uma nova conversão posterior as restaura.

Limitações (v1)

As macros podem conter transformações de tabela, importações e exportações, porque as leituras e gravações de tabelas ficam isoladas no esquema de rascunho da chamada. Importações de dimensão e etapas que atualizam dimensões não são permitidas porque as dimensões são um estado global do projeto. Outras etapas com efeitos colaterais fora de tabelas, como operações com documentos e chamadas a agentes, não são seguras para macro na v1.
As macros precisam estar no mesmo projeto do chamador. Macros entre projetos ainda não são suportadas.
Uma etapa Macro Run não pode ser chamada a partir de uma etapa Executar fluxo de trabalho, de uma etapa Workflow Loop ou de uma etapa Executar fluxo de trabalho condicional — essas etapas são executadas sem isolamento e quebrariam o contrato de esquema por execução. Use uma etapa Macro Run no chamador.

Próximos passos

Referência da etapa Macro Run — a referência campo a campo da etapa chamadora.
Referência da etapa Macro Concurrent — execute uma chamada da macro por linha da tabela de direcionamento.
Etapa Executar fluxo de trabalho — para subfluxos de trabalho que não precisam de isolamento por chamada.