Referências de expressões para fluxos de dados e grafos de fluxo de dados

Essa referência se aplica a fluxos de dados e grafos de fluxo de dados. Ambos usam a mesma linguagem de expressão para transformações de mapa, filtro e enriquecimento. Os grafos de fluxo de dados também dão suporte a transformações de ramificação e janela (acumulação), que são anotadas quando aplicável.

Variáveis posicionais

A matriz de inputs cada regra determina as variáveis disponíveis no expression. A primeira entrada se torna $1, a segunda se torna $2e assim por diante.

Se apenas uma entrada for especificada e nenhuma expressão for fornecida, o valor nessa entrada será copiado diretamente para a saída.

Operadores

As expressões dão suporte aos seguintes operadores, listados da precedência mais alta para a mais baixa:

O + operador concatena cadeias de caracteres quando pelo menos um operando é uma cadeia de caracteres. Use parênteses para substituir a precedência padrão.

Exemplos:

Funções internas

Funções de conversão de unidade

Essas funções aceitam um único valor numérico e retornam um float.

Funções de dimensionamento e arredondamento

Funções matemáticas

Essas funções vêm da biblioteca de matemática interna.

Funções de cadeia de caracteres

Funções de data e hora

Funções de data e hora estão disponíveis apenas em gráficos de fluxo de dados. Exceto por parse_timestamp, funções que aceitam um carimbo de tempo requerem uma string RFC 3339 . A cadeia deve incluir um deslocamento explícito em relação ao Tempo Universal Coordenado (UTC), como 2026-06-17T12:00:00Z ou 2026-06-17T12:00:00-08:00. A Returns coluna lista o tipo de resultado conceitual, que typeof relata em minúsculas como "float", "int", ou "string".

now() lê o clock do sistema do nó Kubernetes que hospeda a carga de trabalho do fluxo de dados a cada execução da função. Chamadas na mesma expressão podem devolver valores diferentes. Em uma regra de acumulação, retorna now() o momento em que a janela é processada, não quando uma mensagem de entrada chega. Para reduzir o desfasamento de clock entre os nós do cluster, sincronize o clock de cada nó com uma fonte de tempo confiável, como um servidor de Protocolo de Tempo de Rede.

Funções de calendário e relógio, como day_of_week, hour_of_day, e year_of, usam o deslocamento no carimbo de hora de entrada. Eles não convertem o valor para UTC primeiro. Os exemplos a seguir mostram esse comportamento.

Formatos e carimbos de tempo de análise

As format_timestamp funções e parse_timestamp usam strftime padrões. A tabela a seguir lista os especificadores comuns.

Para todos os especificadores suportados, veja a documentação do Chrono strftime.

format_timestamp preserva o deslocamento do carimbo de tempo de entrada. Por exemplo, format_timestamp("2026-06-09T14:00:00+02:00", "%Y-%m-%d %H:%M %:z") retorna "2026-06-09 14:00 +02:00".

parse_timestamp lida com as entradas na seguinte ordem:

1. Uma data e hora com um deslocamento numérico. A função respeita o deslocamento e normaliza o resultado para UTC.
2. Uma data e hora sem deslocamento. A função assume UTC.
3. Um encontro sem horário. A função assume a meia-noite UTC.

Os exemplos a seguir mostram como parse_timestamp lida com cada tipo de entrada.

Converter valores de época Unix

Use from_epoch e to_epoch para converter entre valores de época Unix e carimbos de data e horário RFC 3339.

from_epoch aceita valores negativos para datas anteriores a 1º de janeiro de 1970. Sua saída tem precisão de milissegundos, então converter microssegundos de época em um carimbo de tempo descarta precisão abaixo de um milissegundo. to_epoch leva em conta o deslocamento UTC do carimbo de tempo e arredonda valores anteriores a 1970 para o número inteiro seguinte inferior para a unidade selecionada.

Funções de data e hora podem ser compostas. Por exemplo, duration_between($1, now(), "days") calcula a idade em dias de um carimbo de data do RFC 3339 fornecido como a primeira entrada da regra. Para ler a hora de um carimbo de tempo após convertê-lo para UTC, use hour_of_day(from_epoch(to_epoch($1, "micros"), "micros")).

Funções condicionais e de coleção

Funções de agregação (somente transformações de janela)

Essas funções estão disponíveis apenas em regras de acúmulo dentro de transformações de janela. Cada um usa uma única variável posicional.

Para obter detalhes sobre como usar funções de agregação, consulte Agregar dados ao longo do tempo.

Lógica condicional

Use a if função para ramificar a lógica dentro de uma expressão:

Use () (o valor vazio) em comparações para detectar campos ausentes.

Campos de metadados

Leia e escreva em metadados de mensagem usando o $metadata. prefixo nos campos ou inputs nos output campos de uma regra. As referências de metadados vão para o caminho do campo, não na própria expressão.

Propriedades de metadados

• Tópico: Funciona para ambos MQTT e Kafka. Contém a cadeia de caracteres em que a mensagem foi publicada. Exemplo: $metadata.topic.
• Propriedade do usuário: No MQTT, refere-se aos pares de chave/valor de forma livre que uma mensagem MQTT pode conter. Por exemplo, se a mensagem MQTT foi publicada com uma propriedade de usuário com a chave "priority" e o valor "high", a $metadata.user_property.priority referência mantém o valor "alto". As chaves de propriedade do usuário podem ser cadeias de caracteres arbitrárias e podem exigir escape: $metadata.user_property."weird key" usa a chave "weird key" (com um espaço).
• Propriedade do sistema: Esse termo é usado para cada propriedade que não é uma propriedade do usuário. No momento, só há suporte para uma única propriedade do sistema: $metadata.system_property.content_type, que lê a propriedade do tipo de conteúdo da mensagem MQTT (se definida).
• Cabeçalho: Esse é o equivalente no Kafka da propriedade de usuário do MQTT. O Kafka pode usar qualquer valor binário para uma chave, mas os fluxos de dados dão suporte apenas a chaves de cadeia de caracteres UTF-8. Exemplo: $metadata.header.priority. Essa funcionalidade é semelhante às propriedades do usuário.

Leitura de metadados

Para fazer referência ao tópico de origem e a uma propriedade do usuário em uma expressão, liste-os como entradas:

Expressão: $1 + "/" + $2

No exemplo a seguir, a propriedade topic do MQTT é mapeada para o campo origin_topic na saída:

Se a propriedade do usuário priority estiver presente na mensagem MQTT, o exemplo a seguir demonstra como mapeá-la para um campo de saída:

Gravar em metadados

Para definir uma propriedade de usuário na mensagem de saída, use $metadata.user_property.<key> como o campo de saída.

Definir um campo de metadados como um valor vazio (()) o remove. Para propriedades do usuário, chaves duplicadas são permitidas.

Você também pode mapear propriedades de metadados para um cabeçalho de saída ou propriedade do usuário. No exemplo a seguir, o MQTT topic é mapeado para o campo origin_topic na propriedade de usuário da saída:

Se a carga útil de entrada contiver um campo priority, o exemplo a seguir demonstrará como mapeá-lo para uma propriedade de usuário MQTT:

O mesmo exemplo para o Kafka:

Há suporte para campos de metadados em regras de mapa, filtro e branch. Elas não estão disponíveis em regras de janela (acumulação).

Último valor conhecido

Use o ? $last sufixo em uma entrada para dizer ao runtime para lembrar o valor mais recente desse campo. Se o campo estiver ausente na mensagem atual, o último valor conhecido será usado.

A ? $last diretiva não diferencia maiúsculas de minúsculas e dá suporte ao espaço em branco flexível.

Há suporte para o último valor conhecido nas regras de mapa, filtro e branch. Ele não está disponível em regras de janela (acumulação).

Valores padrão

Use o ?? <default> sufixo em uma entrada para fornecer um valor de fallback quando o campo estiver ausente. Tipos padrão com suporte: inteiro, float, booliano, cadeia de caracteres e nulo.

Combinar o último valor conhecido e o padrão

Você pode combinar ? $last e ?? <default>. O runtime verifica a mensagem atual primeiro, depois o último valor conhecido e, em seguida, o padrão. Se você usar ?? <default> sem ? $last, o runtime verificará a mensagem atual e, em seguida, o padrão diretamente.

Os valores padrão têm suporte nas regras de mapa, filtro e branch. Elas não estão disponíveis em regras de janela (acumulação).

Tipos de dados

Objetos JSON e matrizes são preservados as-is quando os campos são copiados sem uma expressão, mas não podem ser usados como entradas para avaliação de expressão.

Suporte a recursos por tipo de transformação

A mesma linguagem de expressões funciona entre transformadas, mas o resultado de uma expressão significa algo diferente em cada uma:

¹ Disponível somente em grafos de fluxo de dados. Não há suporte em entradas de fluxo builtInTransformation de dados.

Notação de ponto e escape

A notação de ponto é amplamente usada para referenciar campos aninhados. Um caminho de notação de ponto padrão se parece Person.Address.Street.Numbercom .

Em um fluxo de dados, um caminho descrito por notação de ponto pode incluir cadeias de caracteres e alguns caracteres especiais sem a necessidade de escape, como Person.Date of Birth.

Em outros casos, o escape é necessário, por exemplo: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Esse caminho, entre outros caracteres especiais, contém os ponto dentro do nome do campo. Sem escapar, o nome do campo serviria como um separador na notação de ponto em si.

Embora um fluxo de dados analise um caminho, ele trata apenas dois caracteres como especiais:

• Os ponto (.) atuam como separadores de campo.
• Aspas duplas, quando colocadas no início ou no final de um segmento, iniciam uma seção escapada onde os pontos não são tratados como separadores de campo.

Todos os outros caracteres são tratados como parte do nome do campo. Essa flexibilidade é útil em formatos como o JSON, em que os nomes de campo podem ser cadeias de caracteres arbitrárias.

A definição do caminho também deve seguir as regras do formato de configuração. Quando um caractere com significado especial é incluído no caminho, aspas adequadas são necessárias. Por exemplo, os nomes de campo que começam com dois-pontos (como :Person:.:name:) ou que começam com um número seguido de texto (como 100 celsius.hot) precisam de aspas na configuração para serem interpretados corretamente como cadeias de caracteres.

Escapando

A função primária de escape em um caminho com notação de ponto é acomodar o uso de ponto que fazem parte de nomes de campo em vez de separadores. Por exemplo, o caminho Payload."Tag.10".Value consiste em três segmentos: Payload, Tag.10e Value. As aspas duplas ao redor Tag.10 impedem que o ponto atue como um separador.

Regras de escape na notação de ponto

• Escape cada segmento separadamente: se vários segmentos contiverem pontos, esses segmentos deverão ser colocados entre aspas duplas. Outros segmentos também podem ser citados, mas isso não afeta a interpretação do caminho. Por exemplo: Payload."Tag.10".Measurements."Vibration.$12".Value

• Cite um segmento apenas quando ele precisar escapar. Adicione aspas duplas ao redor de um segmento apenas quando ele contiver um ponto (ou outro caractere que, de outra forma, seria interpretado erroneamente como separador). Não cite um nome comum de campo.

  Por exemplo, para um corpo nomeado TagName dentro Recordsde :

  Faça isto	Não é isso
  Records.TagName	Records."TagName"

  As aspas extras não ajudam, e em algumas ferramentas, como o editor de fluxo de dados de experiência operacional, elas passam a fazer parte do nome do campo. O mapeamento então procura um campo nomeado "TagName" (aspas incluídas), que não existe, então nada bate. Você pode identificar isso na definição de fluxo de dados exportados, onde o nome aparece com aspas escapadas, como \"TagName\". Para corrigir, remova as aspas para que o nome fique apenas TagName.

• Uso adequado de aspas duplas: aspas duplas devem abrir e fechar um segmento escapado. As aspas no meio do segmento são consideradas parte do nome do campo. Por exemplo, o caminho Payload.He said: "Hello", and waved define dois campos: Payload e He said: "Hello", and waved. Quando um ponto aparece nessas circunstâncias, ele continua a servir como separador. Por exemplo, o caminho Payload.He said: "No. It is done" é dividido nos segmentos PayloadHe said: "Noe It is done" (começando com um espaço).

Algoritmos de segmentação

• Se o primeiro caractere de um segmento for uma aspa, o analisador procurará a próxima aspa. A cadeia de caracteres entre essas aspas é considerada um único segmento.
• Se o segmento não começar com uma aspa, o analisador identificará segmentos pesquisando o próximo ponto ou o final do caminho.

Curingas

Use um curinga (*) em caminhos de entrada e saída para corresponder a vários campos ao mesmo tempo. Isso é útil quando a saída se assemelha muito à entrada ou quando você precisa aplicar a mesma transformação em muitos campos sem listar cada um deles.

Copiar todos os campos

Para passar todos os campos por inalterado:

Corresponde * a cada caminho de campo na entrada e o coloca no mesmo caminho na saída. A parte do caminho correspondente * é chamada de segmento capturado. Na saída, o segmento capturado substitui o *.

Nivelar campos aninhados

Para mover campos de um objeto aninhado para o nível raiz, coloque o prefixo na entrada e * na saída:

Considerando esta entrada:

{
  "Sensors": { "Temperature": 72.5, "Pressure": 14.7 },
  "Metadata": { "LineId": "Line-3", "Shift": "A" }
}

A saída nivela ambos os objetos:

{
  "Temperature": 72.5,
  "Pressure": 14.7,
  "LineId": "Line-3",
  "Shift": "A"
}

Reestruturar campos

Para mover campos em um novo pai, coloque * a entrada e adicione um prefixo na saída:

Isso encapsula todos os campos de nível superior dentro de um Telemetry objeto.

Regras de posicionamento curinga

• Somente um* é permitido por caminho de entrada ou saída.
• Deve * corresponder a um segmento completo (não um segmento parcial como Sensor*).
• Pode * aparecer no início (*.Value), no meio (Sensors.*.Reading) ou no final (Sensors.*) de um caminho.

Curingas de entradas múltiplas

Quando uma regra tem várias entradas com curingas, ela * deve capturar o mesmo segmento em todas as entradas. O runtime resolve a * partir da primeira entrada e procura caminhos correspondentes nas outras entradas.

Por exemplo, para média das leituras máxima e mínima para cada sensor:

Considerando esta entrada:

{
  "Temperature": { "Max": 85.3, "Min": 62.1 },
  "Pressure": { "Max": 15.2, "Min": 14.1 }
}

A * captura Temperature primeiro, de modo que a regra procura por ambos Temperature.Max e Temperature.Min. Em seguida, ele captura Pressure e procura Pressure.Max e Pressure.Min. A saída é:

{
  "Averaged": { "Temperature": 73.7, "Pressure": 14.65 }
}

Se qualquer entrada não puder ser resolvida para um segmento capturado (por exemplo, *.Mid.Avg quando o campo estiver aninhado de forma diferente), esse segmento será ignorado. Verifique se os caminhos em todas as entradas refletem a estrutura real dos dados.

Substituir um curinga para campos específicos

Você pode combinar uma regra curinga com regras específicas. Regras específicas têm precedência quando têm uma cobertura menor (menos segmentos correspondentes por *). Isso é chamado de especialização.

A primeira regra se aplica a todos os campos. A segunda regra substitui-a apenas porque PressurePressure.Max é mais específica do que *.Max (cobertura 0 versus cobertura 1).

Para excluir um campo inteiramente, use uma saída vazia:

Uma saída vazia remove o campo do resultado. Isso substitui qualquer regra curinga que, de outra forma, a incluiria.

Várias regras nas mesmas entradas

Se duas regras tiverem a mesma cobertura ou maior, ambas se aplicarão. Isso permite calcular vários valores derivados das mesmas entradas:

Ambas as regras são executadas para cada segmento capturado, produzindo dois campos de saída por sensor.

Caracteres curinga em conjuntos de dados de contextualização

Você pode usar curingas com $context referências para copiar todos os campos de um conjunto de dados:

Isso copia todos os campos do conjunto de assetMeta dados para a Asset seção da saída.

Conjuntos de dados de contextualização

Os conjuntos de dados de contextualização permitem que os mapeamentos integrem dados extras de bancos de dados externos. Use o $context(datasetName) prefixo para referenciar campos de um conjunto de dados. Por exemplo, $context(position).BaseSalary lê o BaseSalary campo de um conjunto de dados chamado position.

Para obter detalhes sobre como configurar conjuntos de dados de contextualização, consulte Enriquecer dados usando fluxos de dados e Enriquecer com dados externos em grafos de fluxo de dados.

Conteúdo relacionado

Se você chegou aqui procurando a sintaxe usada em uma transformação específica, estes artigos mostram expressões em contexto:

Para fluxos de dados, veja Mapear dados usando fluxos de dados e Filtrar dados em um fluxo de dados.