Variáveis

Uma variável carrega um valor calculado na hora da execução para dentro dos nós do Dataflow. A mais usada é a {StartDate}, que a carga de Extração Janela preenche com o começo do período pedido, mas o mecanismo é geral e vale para qualquer nó.

São três formas de consumir uma variável, e cada nó aceita uma. Em campo de texto você escreve o nome entre chaves e o Agente ETL troca pelo valor antes de executar o nó. Em nó de código não há substituição nenhuma, e o Agente declara a variável de verdade no topo do script. Em filtro declarativo, como o do Lakehouse, você aponta para a variável em vez de escrever o valor.

Onde	Como se escreve
SQL, DuckDB, HTTP Request, qualquer campo de texto	{StartDate}
Python e C#	StartDate
Filtro do Lakehouse	escolha Variável e selecione na lista

Em SQL, DuckDB e HTTP Request

A substituição roda em todo campo de texto do nó, recursivamente. Isso significa que a mesma escrita funciona na consulta de um extrator, na URL de um HTTP Request, num parâmetro de querystring, num cabeçalho e no corpo da requisição.

SELECT * FROM vendas
WHERE DATA_EMISSAO BETWEEN '{StartDate}' AND '{EndDate}'

https://api.erp.com.br/pedidos?desde={StartDate}&ate={EndDate}

Quando a variável não existe, o texto original fica no lugar. Um {StartDate} que chega literal ao banco é o sintoma de que a Extração não estava ativa naquela execução, e é assim que se percebe o problema.

Formato

Depois de dois-pontos você pede um formato. Data usa o padrão do .NET.

Escrito assim	Vira
{StartDate}	2026-08-11
{StartDate:yyyy-MM}	2026-08
{StartDate:dd/MM/yyyy}	11/08/2026
{StartDate:yyyyMMdd}	20260811
{StartDate:unix}	1786752000
{StartDate:unixms}	1786752000000

unix e unixms resolvem o caso da API que espera timestamp, em segundos e em milissegundos.

WARNING

MM é mês e mm é minuto. {StartDate:yyyy-mm} não dá erro, roda e devolve o ano seguido do minuto, o que passa despercebido até alguém conferir o número. O ano é yyyy minúsculo.

Em Python

Nó de código fica fora da substituição de texto, porque trocar {} dentro de código quebraria dicionário e f-string. As variáveis chegam de outro jeito: o Agente ETL escreve uma atribuição para cada uma no topo do script, já convertida para o tipo do Python. Você usa o nome puro, sem chaves.

df = df[df["DATA_EMISSAO"] >= StartDate]

A conversão respeita o tipo de origem, então a variável chega pronta para uso.

Tipo da variável	Como chega no script
Data	datetime.datetime(2026, 8, 11, 0, 0, 0)
Número	número puro, com ponto decimal
Texto	string entre aspas, com escape aplicado
Booleano	True ou False
Vazio	None

StartDate em Python é um datetime, não texto. Comparar direto com uma coluna de data funciona, e formatar exige strftime como qualquer outro datetime.

O nó de código em C# segue a mesma ideia, com as variáveis declaradas antes do seu código.

Em filtro declarativo

O Lakehouse não recebe SQL, e sim uma regra de filtro montada na tela. Cada condição tem um par de botões que decide de onde vem o valor: Valor literal abre um campo para você digitar, e Variável troca o campo por uma lista das variáveis disponíveis naquele fluxo.

A lista traz tudo que existe na execução, incluindo as globais do tenant e as que um Configurador produziu antes no mesmo fluxo. Para recortar por período, escolha StartDate e EndDate nas duas pontas de um filtro between.

Pelo Lumo CLI a mesma condição é escrita como { var: "StartDate" } no YAML. Detalhes em Lakehouse.

De onde as variáveis vêm

Sistema e carga

Injetadas em toda execução, sem configuração.

Variável	O que carrega
StartDate	começo do período, nas cargas de Extração Janela
EndDate	fim do período, nas cargas de Extração Janela
LastDataPoint	ponto de corte da Extração Incremental, o maior valor já carregado no destino
LoadType	a Extração do Dataflow
LoadTypeField	a coluna de janela ou de corte
LoadContext	o contexto pedido na execução
FlowId	id do Dataflow
TenantId	id do tenant
FlowHash	hash da definição do Dataflow naquela execução

Fora de uma carga de Janela, StartDate e EndDate vêm com um intervalo aberto, de 1910 a 2100, para que uma consulta que usa as duas continue funcionando sem recortar nada.

Ambiente da máquina do Agente

Cada variável de ambiente da máquina onde o Agente ETL roda entra com o prefixo ENV_. Uma DB_HOST no sistema operacional vira {ENV_DB_HOST} no Dataflow. Só entram os nomes formados por letra, número e sublinhado.

Serve para o que muda de máquina para máquina e não deve morar no Dataflow, como caminho de rede e host de um servidor local.

Globais do tenant

Uma variável global vale para todos os Dataflows do tenant, e existe para o valor que se repete em muitos fluxos e muda de uma vez só. Lista de filiais, URL base de uma API, data de corte da migração, conjunto de tipos de documento aceitos.

ORGANIZATION_IDS = 101, 102, 103, 104, 105
API_BASE_URL     = https://api.empresa.com/v2
DATA_CORTE       = 2020-01-01

SELECT * FROM vendas WHERE organization_id IN ({ORGANIZATION_IDS})

Para criar, abra Variáveis Globais no editor de Dataflows, clique em Nova Variável e preencha nome e valor. Use maiúsculas e sublinhado no nome, sem espaço.

Acrescentar uma filial vira uma edição só: todos os fluxos que citam {ORGANIZATION_IDS} passam a incluí-la na execução seguinte.

Do Dataflow

Você declara as suas na tela do Dataflow, com nome e valor. Elas valem só para aquele fluxo e são o lugar certo para o parâmetro que se repete em várias consultas do mesmo Dataflow sem fazer sentido para os outros.

Criadas em tempo de execução

O nó Configurador Python existe para calcular variável, e não para transformar dado. Ele roda um script Python e tudo que estiver no dicionário variables no fim do script vira variável para os nós seguintes.

import datetime

ontem = datetime.date.today() - datetime.timedelta(days=1)

variables = {
    "DataCorte": ontem.strftime("%Y-%m-%d"),
    "Filiais": "1,2,7",
}

Depois disso, {DataCorte} e {Filiais} funcionam em qualquer nó posterior, e em Python chegam como DataCorte e Filiais.

O script precisa preencher variables. Se ele terminar sem definir nada, a execução falha com "Nenhuma variável foi configurada pelo script", em vez de seguir com um valor vazio que ninguém veria.

O Configurador é a saída para o que a configuração pronta não cobre: recuar o ponto de corte de uma carga Incremental, montar a conexão na hora, fazer um nó ler vários bancos, gerar a consulta a partir de um de-para. Cada um desses tem exemplo em Configurador Python.

O ${item} do HTTP Request

O HTTP Request tem um laço de entrada que repete a mesma chamada para cada valor de uma lista. Dentro dele, o valor da vez é escrito com cifrão antes das chaves, e substitui na URL e nos campos de autenticação.

https://api.erp.com.br/filiais/${filial}/pedidos?desde={StartDate}

Os dois marcadores convivem na mesma URL e não se confundem. O ${filial} muda a cada volta do laço, e o {StartDate} vale para a execução inteira.

Fora do laço de entrada do HTTP Request, o cifrão não faz nada. Escrever ${ORGANIZATION_IDS} numa consulta SQL deixa o cifrão sobrando no texto final e quebra a consulta.

Relacionados

• Tipos de Carga: quem preenche StartDate, EndDate e LastDataPoint, e quando
• Execução e Agendamento: o contexto que define o período de cada execução
• HTTP Request: usar variável em URL, cabeçalho e corpo
• Lakehouse: filtro declarativo com var