Variáveis

Tipo

Referência

Para

Engenharia de dados, Desenvolvedor

Na tela

HorusETL › Data Flows › editor do Dataflow › Variáveis Globais

Variáveis levam para dentro dos nós valores que só se conhecem na execução, como o começo da janela de datas ou o token de uma API. Para criar variáveis com código antes da carga, ver Calcular variáveis na hora da execução.

Campos

Como escrever

Onde	Como se escreve
SQL, URL, cabeçalho, corpo e todo campo de texto de um nó	{StartDate}
Nó de código Python	StartDate, como variável do script
Nó Map C#	StartDate, como variável do código
Filtro do nó Consultar Lakehouse	escolha Variável e selecione na lista
Laço de entrada do nó Requisição HTTP	${filial}, o valor da volta; ver Requisição HTTP

O nome aceita letras, números e sublinhado. A troca vale em todo campo de texto do nó, menos no código-fonte dos nós de código. Uma variável que não existe fica no texto como foi escrita: um {StartDate} que chega literal ao banco indica que a variável não estava definida naquela execução.

Formato

Depois de dois-pontos vem o formato. Data usa o padrão de data do .NET.

Escrito	Vira
{StartDate}	2026-08-11
{StartDate:yyyy-MM}	2026-08
{StartDate:dd/MM/yyyy}	11/08/2026
{StartDate:yyyyMMdd}	20260811
{StartDate:unix}	timestamp em segundos
{StartDate:unixms}	timestamp em milissegundos

MM é mês e mm é minuto: {StartDate:yyyy-mm} roda sem erro e devolve o ano seguido do minuto.

Uma variável de texto escrita como data (2026-08-11, com hora opcional, como 2026-08-11 10:30:00 ou 2026-08-11T10:30:00Z) também é tratada como data: aceita formato e chega ao Python como datetime. A partir do Agente ETL 1.29.3, usada sem formato ela sai do jeito que foi escrita, em qualquer origem. Variável numérica, como um LastDataPoint de coluna numérica ou um número devolvido por Configurador, aceita o formato numérico do .NET, como {LastDataPoint:000000}. Texto que não é data não aceita formato, e a execução falha com Error formatting variable; um valor digitado na tela, mesmo que seja 1.5, é texto.

No Python

Tipo da variável	Chega no script como
Data	datetime.datetime
Número	número
Texto	str
Booleano	True ou False
Vazia	None

Variáveis de sistema

O Agente ETL define estas em toda execução, por cima das globais e das do Dataflow:

Variável	Valor
StartDate	começo da janela; fora de uma execução por janela, 01/01/1910
EndDate	fim da janela; fora de uma execução por janela, 01/01/2100
LastDataPoint	ponto de corte da Extração Incremental: o maior valor da coluna de corte no destino, com o tipo dela; 0 fora do Incremental
LoadType	a Extração do Dataflow
LoadTypeField	a coluna de janela ou de corte
LoadContext	o contexto da execução, como Temporal:Days:3
WriteMode	a Gravação em uso
FlowId	id do Dataflow
TenantId	id do Tenant
FlowHash	identificador da versão do Dataflow nessa execução

AgentName, o nome do Agente ETL que executa, chega junto com as globais; uma variável do Dataflow com o mesmo nome o substitui.

O Tenant pode ter um limite de data para cargas temporais, definido pelo administrador no HEC como "carregar dados dos últimos N dias, meses ou anos". Com ele, StartDate nunca fica antes desse limite, nem no contexto Total.

De onde vêm as outras

Origem	Onde se define	Vale para
Global	Variáveis Globais, no editor do Dataflow ou em Conexões	todos os Dataflows do Tenant
Global, valor por agente	Valor por agente, na mesma variável	só o Agente ETL indicado
Do Dataflow	Variáveis de Desenvolvimento, no editor	só aquele Dataflow, no editor e no agendamento
Ambiente da máquina	variável de ambiente do sistema, lida como ENV_NOME	os Dataflows daquele Agente
Configurador	o script ou a chamada HTTP	os nós seguintes do mesmo Dataflow

Quando o mesmo nome existe em mais de um lugar, vale, do mais fraco para o mais forte: global, valor por agente, do Dataflow, sistema. As ENV_ entram junto com as de sistema e também vencem as anteriores. O Configurador roda depois de tudo isso, e o que ele devolve substitui qualquer variável de mesmo nome, inclusive as de sistema. O Agente que não tem valor próprio usa o valor geral da global; um Agente nunca recebe o valor de outro.

Campos da variável global

Na tela	Regra
Nome	letras, números e sublinhado, sem começar por número; use maiúsculas, como API_BASE_URL
Descrição	texto livre
Protegida	"O valor não aparece mais na tela depois de salvo. Use para senha e token." Os valores por agente também ficam ocultos. Renomear ou desproteger pede o valor de novo
Valor	o valor geral
Valor por agente	um valor para cada Agente ETL que precisar; aparece quando o Tenant tem mais de um Agente

Ao instalar um template do HEC num segundo Agente, Só neste agente, ao lado da variável, grava o valor digitado só para esse Agente e deixa o dos outros como estava.

Exemplo

ORGANIZATION_IDS = 101, 102, 103
API_BASE_URL     = https://api.exemplo.com.br/v2

SELECT * FROM vendas
WHERE organization_id IN ({ORGANIZATION_IDS})
  AND data_emissao BETWEEN '{StartDate:yyyy-MM-dd}' AND '{EndDate:yyyy-MM-dd}'

{API_BASE_URL}/pedidos?desde={StartDate:unix}&loja=${loja}

Limites

• Não há escape: {NOME} com o nome de uma variável existente sempre é trocado, em qualquer campo de texto.
• Só entram como ENV_ as variáveis de ambiente cujo nome tem apenas letras, números e sublinhado.
• O ${...} só funciona dentro do laço de entrada do nó Requisição HTTP. Numa consulta SQL, o cifrão sobra no texto e quebra a consulta.
• Variável do Dataflow vence a global de mesmo nome. Se uma global não está chegando, confira se o Dataflow não tem uma variável de desenvolvimento com o mesmo nome, por exemplo uma criada ao testar um Configurador no editor.
• Dois Configuradores no mesmo Dataflow não têm ordem garantida entre si; se um depende do outro, junte os dois num só.

Pelo Lumo CLI

Este recurso também pode ser criado e versionado em YAML. Veja a referência de variables.