python script¶

fábrica

transformação customizada escrita em python — a válvula de escape para lógica que não é expressável nos nós lowcode ou em sql. você escreve uma função transform(df) que recebe os dados de entrada como um dataframe e deve retornar um dataframe com o resultado.

quando usar¶

lógica de negócio complexa demais para um WHERE/CASE WHEN (ex: regras condicionais encadeadas, parsing de texto customizado)
integração com bibliotecas python específicas do seu domínio (validação de documentos, regras de compliance, cálculos especializados)
prototipagem rápida de uma transformação antes de decidir se vale a pena reescrevê-la como um nó lowcode reutilizável

se a transformação pode ser expressa em sql ou em um dos nós lowcode (filtrar, agregar, mapear...), prefira esses — são mais fáceis de ler, revisar e manter no médio prazo.

configuração¶

campo	tipo	obrigatório	descrição
`script`	string	sim	código python contendo a função `transform(df)`
`requirements`	lista	não	bibliotecas python adicionais exigidas pelo script

contrato da função¶

import pandas as pd

# `df` é o dataframe de entrada (dados do nó anterior)
# a função deve retornar um dataframe
def transform(df: pd.DataFrame) -> pd.DataFrame:
    return df

df chega como um DataFrame com as colunas e linhas da tabela upstream
a função precisa retornar um DataFrame (ou uma lista de dicionários) — esse retorno vira a tabela de saída do nó
variáveis do pipeline ficam disponíveis dentro do script através do dicionário pipeline

exemplo¶

import pandas as pd

def transform(df: pd.DataFrame) -> pd.DataFrame:
    # normaliza e-mails para minúsculo
    df["email"] = df["email"].str.lower().str.strip()

    # cria uma coluna derivada com regra de negócio customizada
    df["segmento"] = df["valor_total"].apply(
        lambda v: "alto" if v > 10000 else ("medio" if v > 1000 else "baixo")
    )

    # remove linhas sem e-mail válido
    df = df[df["email"].str.contains("@", na=False)]

    return df

testando o script no builder¶

ao testar o nó individualmente no editor, a função transform é executada contra uma amostra de dados simulada — isso permite validar erros de sintaxe e o formato de retorno antes de conectar o nó a uma fonte real. a saída do teste mostra as colunas e as primeiras linhas do resultado, além de qualquer saída de print() usada para depuração.

a função deve sempre retornar um dataframe

se transform não retornar um DataFrame (ou uma lista de dicionários), o nó falha. evite modificar df sem retorná-lo ao final da função.

prefira nós lowcode quando possível

scripts python são mais difíceis de revisar em um pipeline visual do que nós dedicados (filtrar, mapear, agregar...). reserve este nó para lógica que realmente não tem equivalente lowcode.