Reutilize o seu trabalho: variáveis, macros e UDF

~30 minutos · uma variável, uma macro, uma transformação definida pelo utilizador

O primeiro fluxo de trabalho que cria costuma ter tudo codificado de forma fixa — uma região, um mês, um nome de tabela. Funciona uma vez. Este tutorial é o salto de utilizador para utilizador avançado: pega nesse pipeline pontual e transforma-o num ativo que pode apontar para qualquer região, chamar a partir de qualquer lugar e estender com o seu próprio Python.

Três ferramentas fazem o trabalho, e complementam-se:

Ferramenta	O que elimina	Recorra a ela quando
Variável de fluxo de trabalho	Valores codificados de forma fixa espalhados por vários passos	O mesmo valor (um mês, uma região, um limiar) aparece em mais do que um passo
Macro	Sequências de passos copiadas e coladas	Uma sequência parametrizada é executada muitas vezes — por região, por mês, por linha de indutores
Transformação definida pelo utilizador (UDF)	A lacuna que os passos padrão não alcançam	Nenhuma transformação padrão (nem combinação delas) faz o que precisa, e pode escrevê-lo em Python

Não precisa das três em todos os fluxos de trabalho. Acrescente cada uma no momento em que o problema que ela elimina realmente aparecer.

Cada ferramenta cobre mais terreno do que a anterior. Acrescente-as quando a necessidade surgir — não antes.

Pré-requisitos

Uma área de trabalho PlaidCloud e um projeto com um fluxo de trabalho que já tenha criado — idealmente o de Carregar, transformar e publicar dados.
À-vontade para adicionar e executar passos de fluxo de trabalho. Se for novidade, comece pelo guia de fluxos de trabalho.

Passo 1: Parametrizar com uma variável de fluxo de trabalho

Uma variável é um valor com nome que os seus passos leem em vez de um literal. Altere-o num só local e todos os passos que o referenciam acompanham. O PlaidCloud mantém as variáveis em dois âmbitos: as variáveis de projeto são partilhadas por todos os fluxos de trabalho do projeto; as variáveis de fluxo de trabalho pertencem a um só fluxo de trabalho e são a forma natural de passar informação entre os respetivos passos.

Na hierarquia de Fluxos de trabalho, clique no ícone de variáveis para abrir a tabela de variáveis.
Adicione uma variável — dê-lhe um nome claro como target_region e defina o seu valor atual (por exemplo, East).
Num passo que atualmente tenha esse valor codificado de forma fixa, referencie a variável em vez de escrever o literal.
Execute o passo. Depois altere o valor da variável na tabela e execute novamente — o mesmo passo processa agora uma fatia diferente, sem qualquer edição ao passo.

A tabela de variáveis é também onde pode ver os valores atuais, editá-los e eliminar as variáveis de que já não precisa.

Âmbito de projeto vs. âmbito de fluxo de trabalho. Coloque um valor no âmbito de projeto quando vários fluxos de trabalho precisam da mesma definição e no âmbito de fluxo de trabalho quando é local aos passos de um só fluxo de trabalho. Em caso de dúvida, comece por um âmbito restrito — uma variável de fluxo de trabalho — e promova-a para o projeto apenas quando um segundo fluxo de trabalho precisar dela.

Para ver em pormenor onde residem as variáveis e como geri-las, consulte Gerir variáveis de fluxo de trabalho.

Passo 2: Empacotar uma sequência como macro

Uma variável parametriza um valor. Uma macro parametriza uma sequência inteira de passos. É um fluxo de trabalho avançado (DAG) reutilizável com um contrato de entrada/saída declarado — pense em “processar um mês de vendas para uma região” — que chama a partir de outro fluxo de trabalho uma vez por mês, por região, ou ambos. Cada invocação é executada no seu próprio esquema temporário isolado, pelo que a mesma macro pode ser executada muitas vezes em simultâneo sem que as execuções colidam.

As macros são uma funcionalidade exclusiva dos fluxos de trabalho avançados. Converta primeiro o fluxo de trabalho para avançado. Os passos dentro de uma macro têm de ser seguros para macros — transformações de tabelas, importações, exportações, passos de variáveis com âmbito de execução e chamadas de macros aninhadas são permitidos; as importações de dimensões e os passos que atualizam dimensões são rejeitados porque as dimensões são estado global do projeto.

Transformar um fluxo de trabalho numa macro

Abra o projeto e, no separador Fluxos de trabalho, selecione o fluxo de trabalho que pretende reutilizar.
No painel Detalhes do fluxo de trabalho, confirme que o Tipo de fluxo de trabalho é Avançado — utilize primeiro Converter para avançado se for Standard.
Na secção Macro, clique em Converter em macro… e confirme. É apresentado um editor de portas.
Clique em Adicionar porta para cada entrada ou saída que a macro aceita ou produz. Para cada porta, defina:
- Nome — o identificador ao qual o chamador se associa (por exemplo, month, region_sales).
- Direção — Entrada (o chamador fornece-a) ou Saída (a macro produz-a).
- Tipo — Tabela, Escalar (uma única cadeia / inteiro / vírgula flutuante / booleano / data) ou Dimensão.
- Obrigatório — desmarque se a macro puder ser executada sem esta porta associada.
- Memorando — uma nota curta apresentada aos autores no formulário de associação do lado do chamador.
Clique em Guardar portas.

Invocá-la a partir de outro fluxo de trabalho

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 — associe cada porta de entrada. As portas escalares e de dimensão aceitam muitas vezes uma variável de fluxo de trabalho do lado do chamador (a do Passo 1); as portas de tabela aceitam uma tabela de origem, opcionalmente com projeção de colunas e filtro.
Output Port Bindings — aponte cada porta de saída para uma tabela de destino do lado do chamador.
Guarde o passo e execute o fluxo de trabalho.

Para executar a macro uma vez por linha de uma tabela de indutores — uma região por linha, por exemplo — utilize antes um passo Macro: Execução em simultâneo e limite quantas são executadas em simultâneo com Execuções em simultâneo. Cada linha obtém o seu próprio esquema temporário e destino.

O guia completo campo a campo, incluindo o ciclo de vida do isolamento de execução, está em Criar uma macro.

Passo 3: Acrescentar lógica personalizada com uma transformação definida pelo utilizador

As transformações padrão cobrem quase tudo e são continuamente otimizadas para desempenho — recorra primeiro a elas. Mas quando nenhum passo padrão (isolado ou em combinação) faz o que precisa, uma transformação definida pelo utilizador (UDF) permite passar para Python padrão, com a API completa do PlaidCloud e pacotes como Pandas, NumPy e SciPy disponíveis.

Pode criar uma UDF de duas formas: escrevê-la e mantê-la diretamente no PlaidCloud, ou apontar para um ficheiro num repositório Git ligado (que recolhe automaticamente as alterações na execução seguinte e suporta ramos e etiquetas para controlo de versões).

Criar a função

Abra o fluxo de trabalho, selecione o separador Definido pelo utilizador e clique em Adicionar função definida pelo utilizador.
Atribua um ID à UDF e clique no ícone Edit function logic para abrir o editor.

Escreva a sua lógica. Uma UDF mínima liga-se, lê uma origem, transforma em Pandas e guarda um destino:

from plaidcloud.utilities.connect import PlaidConnection
from plaidcloud.utilities import frame_manager as fm

conn = PlaidConnection()

# Read a table configured as a source on the step
source = conn.udf.source_by_name('sales_clean')
df = conn.get_data(source)

# Custom logic the standard steps don't cover
df['margin_band'] = df['margin'].apply(
    lambda m: 'high' if m > 0.4 else 'low'
)

# Write to a table configured as a target on the step.
# Sources are read by their configured name; fm.save writes to a table PATH (leading slash).
fm.save(df, name='/output/sales_scored', append=False)

Adicioná-la ao fluxo de trabalho

No separador Analyze Steps, adicione um passo User Defined Transform onde precisar, tal como uma transformação padrão.
Na configuração do passo, escolha o tipo: UDF do Analyze (uma função guardada) ou Repositório externo de código-fonte (Git — depois escolha Ligação, Ramo e Caminho do ficheiro).
Defina as tabelas de origem e de destino que a UDF utiliza. Pode aceder diretamente às tabelas no código, mas declará-las aqui regista as dependências e disponibiliza-as através de conn.udf.source_by_name(...) / target_by_name(...).
Opcionalmente, acrescente valores específicos do passo em Outras variáveis, legíveis com conn.udf.variable_by_name(...).

Declare as suas tabelas na configuração, não apenas no código. Uma UDF que lê uma tabela diretamente continua a ser executada, mas o PlaidCloud não saberá que a tabela é uma dependência — pelo que a linhagem e a ordenação das execuções não a podem ter em conta. Listar origens e destinos na configuração do passo mantém o grafo de dependências fiel à realidade.

As variáveis de projeto e de fluxo de trabalho do Passo 1 também são acessíveis dentro da UDF, através de conn.analyze.workflow.variable_values(...) e conn.analyze.project.variable_values(...) — pelo que o mesmo parâmetro controla os seus passos padrão e o seu código personalizado. Encontra exemplos completos da API na referência do passo User Defined Transform.

Este é o salto de utilizador para utilizador avançado. Transformou um pipeline pontual em ativos reutilizáveis — um valor que pode reapontar com uma variável, uma sequência inteira que pode chamar em qualquer lugar como macro e Python personalizado que alcança o que os passos padrão não conseguem.

Para onde ir a seguir

Gerir variáveis de fluxo de trabalho — âmbito de projeto vs. de fluxo de trabalho, e a tabela de variáveis.
Criar uma macro — portas, isolamento de execução e uma macro por linha.
Referência do passo User Defined Transform — toda a superfície da API para Python personalizado.
Guia de fluxos de trabalho — condições, ciclos e tudo o resto que a camada de orquestração oferece.
Transformar dados com SQL — o tutorial irmão para quando a resposta é uma consulta, não código.