Criar uma macro

Uma macro é um fluxo de trabalho avançado (DAG) reutilizável, com um contrato de entrada/saída declarado. Invoca uma macro a partir de outro fluxo de trabalho com um passo Macro Run ou Macro Concurrent. Cada invocação é executada no seu próprio esquema de trabalho isolado, pelo que a mesma macro pode ser chamada em simultâneo a partir de vários fluxos principais ou de várias linhas de indutores sem que as execuções colidam.

Utilize uma macro quando tiver uma transformação de dados repetível e parametrizada (por exemplo, «processar um mês de dados de vendas para uma região») que pretenda chamar a partir de um fluxo de trabalho de indutores, uma vez por mês, por região ou ambos. O chamador associa tabelas e variáveis às portas de entrada declaradas da macro; quando termina, as tabelas de saída declaradas são copiadas para os destinos do lado do chamador.

Passos

Abra o projeto que contém o fluxo de trabalho que pretende transformar numa macro.
Mude para o separador 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, utilize primeiro a ação Converter para avançado.
Na secçã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 de macro e aparece um editor de portas.
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 utiliza para se associar a esta porta (por exemplo, month, region_sales).
- Direção — Entrada (o chamador fornece este valor ou tabela) ou Saída (a macro produz-o e o chamador recolhe-o).
- Tipo — Tabela para uma tabela de dados, Escalar para um único valor (cadeia de caracteres / inteiro / vírgula flutuante / booleano / data) 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 esteja associada.
- Memorando — uma nota curta sobre o que esta porta representa, apresentada aos autores no formulário de associação do lado do chamador.
Clique em Guardar portas.

O fluxo de trabalho é agora uma macro. Os autores que adicionarem um passo Macro Run noutro fluxo de trabalho verão as suas portas declaradas e associar-se-ão a elas pelo nome.

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

Invocar uma macro

No fluxo de trabalho chamador:

Adicione um passo Macro: Executar.
Em Macro a executar, selecione o projeto e o fluxo de trabalho da macro.
Input Port Bindings — para cada porta de entrada que a macro declara, adicione uma associaçã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 escalares de entrada da macro), para que só a fatia necessária seja materializada no esquema de execução da macro.
- As portas Escalar / Dimensão recebem um valor (muitas vezes 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 o possa referenciar.
Output Port Bindings — para cada porta de saída que a macro produz, aponte-a para uma tabela de destino do lado do chamador (criada no momento, se ainda não existir).
Guarde o passo.

Quando o fluxo de trabalho principal é executado e chega ao passo Macro Run, o executor:

Cria um novo run_id para esta invocação da macro.
Cria um esquema de trabalho por execução (macrorun_<run_id>) no catálogo do projeto.
Copia as tabelas de entrada associadas para o esquema de trabalho (a projeção de colunas e o filtro são aplicados na cópia de entrada, pelo que o filtro é empurrado para a origem).
Define as variáveis escalares / de dimensão de entrada associadas na sobreposição de variáveis com âmbito de execução da macro.
Executa os passos da macro no mesmo processo. Todos os passos SQL dentro da macro leem e escrevem no esquema de trabalho em vez do esquema do projeto.
Copia as tabelas de saída declaradas de volta para os destinos do chamador.
Elimina o esquema de trabalho (sempre, mesmo que um passo dentro da macro tenha falhado).

Cada invocação recebe um novo run_id e o seu próprio esquema de trabalho. Os passos leem e escrevem apenas nesse esquema, que é eliminado quando a execução termina, quer com êxito, erro ou paragem.

Como cada invocação tem o seu próprio esquema de trabalho, duas chamadas em simultâneo à mesma macro (a partir de um ciclo, de uma distribuição ou de fluxos de trabalho independentes) nunca colidem nos nomes das tabelas intermédias.

Executar uma macro por linha de indutores

Utilize Macro: Execução em simultâneo quando uma tabela do chamador deve conduzir muitas invocações independentes da macro.

Adicione um passo Macro: Execução em simultâneo.
Em Indutor, selecione a tabela de indutores do lado do chamador e defina Execuções em simultâneo com o número máximo de invocações filhas da macro a executar ao mesmo tempo.
Em Seleção de dados da tabela, mapeie as colunas da tabela de indutores de que cada invocação filha precisa.
Em Filtro do driver, restrinja opcionalmente as linhas de indutores a processar.
Em Macro, selecione o fluxo de trabalho da macro.
Em Associações de entrada, associe os valores das colunas de indutores às variáveis escalares ou de dimensão da macro e associe tabelas do lado do chamador às portas de tabela da macro.
Em Associações de saída, mapeie as portas de saída da macro para tabelas de destino do lado do chamador.

Cada linha de indutores selecionada recebe um run_id e um esquema de trabalho separados. Parar o passo principal pára todas as invocações filhas ativas e elimina os respetivos esquemas de execução.

Uma invocação por linha de indutores, cada uma no seu próprio esquema de trabalho, pelo que as tabelas intermédias nunca colidem. Execuções em simultâneo limita quantas são executadas ao mesmo tempo, e cada linha escreve a sua própria tabela results_{region}.

Despromover uma macro

Pode remover a marca de macro em qualquer altura, clicando em Despromover para avançado… no painel Detalhes do fluxo de trabalho. O fluxo de trabalho volta a ser um fluxo de trabalho avançado simples e quaisquer passos Macro Run do lado do chamador que o referenciem falharão em tempo de execução com um erro «not a macro». As portas declaradas permanecem no registo, pelo que uma nova conversão posterior as restaura.

Limitações (v1)

As macros podem conter transformações de tabelas, importações e exportações, porque as leituras e escritas de tabelas ficam isoladas no esquema de trabalho da invocação. As importações de dimensões e os passos que atualizam dimensões não são permitidos, porque as dimensões são um estado global do projeto. Outros passos com efeitos secundários que não envolvam tabelas, como operações com documentos e chamadas a agentes, não são seguros para macros na v1.
As macros têm de estar no mesmo projeto que o chamador. As macros entre projetos ainda não são suportadas.
Um passo Macro Run não pode ser invocado a partir de um Run Workflow, de um Workflow Loop nem de um Run Workflow condicional: estes passos são executados sem isolamento e quebrariam o contrato do esquema por execução. Utilize antes um passo Macro Run no chamador.

Passos seguintes

Referência do passo Macro Run — a referência campo a campo do passo chamador.
Referência do passo Macro Concurrent — executa uma invocação da macro por linha da tabela de indutores.
Passo Run Workflow — para subfluxos de trabalho que não precisam de isolamento por invocação.