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

Esta referência aplica-se tanto a fluxos de dados como a grafos de fluxo de dados. Ambos utilizam a mesma linguagem de expressão para transformações de mapeamento, filtro e enriquecimento. Os grafos de fluxo de dados também suportam transformações de ramificação e janela (acumulação), que são indicadas quando aplicável.

Variáveis posicionais

O array de inputs cada regra determina as variáveis disponíveis no expression. A primeira entrada torna-se $1, a segunda torna-se $2, e assim sucessivamente.

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

Operadores

As expressões suportam os seguintes operadores, listados da maior para a menor precedência:

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

Exemplos:

Funções incorporadas

Funções de conversão unitária

Estas funções aceitam um único valor numérico e devolvem um float.

Funções de escala e arredondamento

Funções Matemáticas

Estas funções vêm da biblioteca matemática incorporada.

Funções de cadeia de caracteres

Funções de data e hora

As funções de data e hora estão disponíveis apenas nos gráficos de fluxo de dados. Exceto para parse_timestamp, as funções que aceitam um carimbo temporal requerem uma cadeia 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 conceptual, que typeof reporta em minúsculas como "float", "int", ou "string".

now() lê o relógio do sistema do nó Kubernetes que aloja a carga de trabalho do fluxo de dados cada vez que a função é executada. Chamadas na mesma expressão podem devolver valores diferentes. Numa regra de acumulação, now() devolve o momento em que a janela é processada, não quando chega uma mensagem de entrada. Para reduzir o desvio de relógio entre nós de cluster, sincronize cada relógio de nó com uma fonte de tempo fiá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 temporal de entrada. Eles não convertem primeiro o valor para UTC. Os exemplos seguintes mostram este comportamento.

Formatos e carimbos temporais de análise sintática

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

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

format_timestamp preserva o deslocamento do carimbo temporal da 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 trata das entradas na seguinte ordem:

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

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

Converter valores de época Unix

Usar from_epoch e to_epoch para converter entre valores de época Unix e carimbos de data RFC 3339.

from_epoch aceita valores negativos para datas anteriores a 1 de janeiro de 1970. A sua saída tem precisão de milissegundos, pelo que converter microssegundos de época num carimbo temporal descarta precisão inferior a um milissegundo. to_epoch tem em conta o deslocamento UTC do carimbo temporal e arredonda valores anteriores a 1970 para o número inteiro seguinte inferior para a unidade selecionada.

Podem ser compostas funções de data e hora. Por exemplo, duration_between($1, now(), "days") calcula a idade em dias de um carimbo temporal do RFC 3339 fornecido como primeira introdução da regra. Para ler a hora de um carimbo de tempo após a converter 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 (apenas transformadas de janela)

Estas funções estão disponíveis apenas em regras de acumulação dentro das transformadas de janela. Cada uma assume uma única variável posicional.

Para detalhes sobre a utilização de funções de agregação, veja 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) nas comparações para detetar campos em falta.

Campos de metadados

Lê e escreve nos metadados da mensagem usando o $metadata. prefixo nos inputs campos or output de uma regra. As referências aos metadados vão no caminho do campo, não na expressão em si.

Propriedades de metadados

• Tópico: Funciona tanto para MQTT quanto para Kafka. Ele contém a cadeia de caracteres onde a mensagem foi publicada. Exemplo: $metadata.topic.
• Propriedade do usuário: No MQTT, isso se refere aos pares chave/valor de forma livre que uma mensagem MQTT pode carregar. Por exemplo, se a mensagem MQTT foi publicada com uma propriedade de utilizador com chave "prioridade" e valor "alto", então 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 fuga: $metadata.user_property."weird key" usa a chave "chave estranha" (com um espaço).
• Propriedade do sistema: este termo é usado para cada propriedade que não é uma propriedade do usuário. Atualmente, apenas uma única propriedade do sistema é suportada: $metadata.system_property.content_type, que lê a propriedade de tipo de conteúdo da mensagem MQTT (se definida).
• Cabeçalho: Este é o equivalente na Kafka da propriedade do utilizador MQTT. Kafka pode usar qualquer valor binário para uma chave, mas os fluxos de dados suportam apenas chaves de cadeia UTF-8. Exemplo: $metadata.header.priority. Essa funcionalidade é semelhante às propriedades do usuário.

Ler a partir dos metadados

Para referenciar o tópico de origem e uma propriedade de utilizador numa expressão, liste-os como entradas:

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

No exemplo a seguir, a propriedade MQTT topic é mapeada para o campo origin_topic no resultado:

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

Escrita para metadados

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

Definir um campo de metadados para um valor vazio (()) remove-o. Para propriedades de utilizador, são permitidas chaves duplicadas.

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

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

O mesmo exemplo para Kafka:

Os campos de metadados são suportados nas regras de mapa, filtro e ramos. Não estão disponíveis nas regras de janela (acumulação).

Último valor conhecido

Use o sufixo ? $last numa entrada para indicar ao tempo de execução que se lembre do valor mais recente desse campo. Se o campo estiver em falta na mensagem atual, é usado o último valor conhecido.

A ? $last diretiva é insensível a maiúsculas e minúsculas e suporta espaços em branco flexíveis.

O último valor conhecido é suportado nas regras de mapa, filtro e ramo. Não está disponível nas regras de janela (acumulação).

Valores padrão

Use o sufixo ?? <default> numa entrada para fornecer um valor de recurso, quando o campo estiver em falta. Tipos padrão suportados: inteiro, float, booleano, string e nulo.

Combinar o último valor conhecido e o padrão

Pode combinar ? $last e ?? <default>. O tempo de execução verifica primeiro a mensagem atual, depois o último valor conhecido e depois o predefinido. Se usares ?? <default> sem ? $last, o tempo de execução verifica diretamente a mensagem atual e depois o predefinido.

Os valores padrão são suportados nas regras de mapa, filtro e ramos. Não estão disponíveis nas regras de janela (acumulação).

Tipos de dados

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

Suporte a funcionalidades 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 apenas em gráficos de fluxo de dados. Não é suportado em entradas de fluxo builtInTransformation de dados.

Notação de pontos e escape

A notação de pontos é amplamente usada para referenciar campos aninhados. Um caminho padrão de notação pontual assemelha-se a Person.Address.Street.Number.

Num fluxo de dados, um caminho descrito por notação de pontos pode incluir cadeias e alguns caracteres especiais sem necessidade de escapar, como Person.Date of Birth.

Noutros casos, a fuga é necessária, por exemplo: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Este caminho, entre outros caracteres especiais, contém pontos dentro do nome do campo. Sem escapar, o nome do campo serviria como um separador na própria notação de pontos.

Enquanto um fluxo de dados analisa um caminho, ele trata apenas dois caracteres como especiais:

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

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

A definição do caminho deve também cumprir as regras do formato de configuração. Quando uma personagem com significado especial é incluída no caminho, é necessária uma citação adequada. Por exemplo, nomes de campos que começam por dois pontos (como :Person:.:name:) ou que começam com um número seguido de texto (como 100 celsius.hot) precisam de ser citados na configuração para serem interpretados corretamente como cadeias de caracteres.

Fuga

A principal função de escapar num caminho notado por pontos é acomodar o uso de pontos que fazem parte dos nomes dos campos em vez de separadores. Por exemplo, o caminho Payload."Tag.10".Value consiste em três segmentos: Payload, Tag.10, e Value. As aspas duplas à volta Tag.10 impedem que o ponto atue como separador.

Escapando de regras na notação de pontos

• Escape cada segmento separadamente: se vários segmentos contiverem pontos, esses segmentos devem 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

• Cita um segmento apenas quando for preciso escapar. Adicione aspas duplas à volta de um segmento apenas quando este contiver um ponto (ou outro carácter que, de outra forma, seria interpretado incorretamente como separador). Não cites um nome comum de campo.

  Por exemplo, para um corpo nomeado TagName dentro Recordsde :

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

  As aspas extra não ajudam e, em algumas ferramentas, como o editor de fluxo de dados de experiência operacional, passam a fazer parte do nome do campo. O mapeamento procura então um campo nomeado "TagName" (aspas incluídas), que não existe, por isso nada corresponde. Pode detetar isto 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. Quaisquer 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 nestas circunstâncias, continua a servir como separador. Por exemplo, o caminho Payload.He said: "No. It is done" é dividido nos segmentos Payload, He said: "No, e It is done" (começando por um espaço).

Algoritmo 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 aspas, o analisador identificará segmentos procurando o próximo ponto ou o final do caminho.

Wildcards

Use um coringa (*) nos caminhos de entrada e saída para corresponder a vários campos ao mesmo tempo. Isto é útil quando a saída se assemelha muito à entrada, ou quando é necessário aplicar a mesma transformação em vários campos sem listar cada um deles.

Copiar todos os campos

Para passar todos os campos sem alterações:

Corresponde * a cada caminho de campo na entrada e coloca-o no mesmo caminho na saída. A parte do caminho que * corresponde chama-se segmento capturado. Na saída, o segmento capturado substitui o *.

Campos aninhados achatados

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

Dado este input:

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

A saída achata ambos os objetos:

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

Reestruturação de campos

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

Isto envolve todos os campos de topo dentro de um Telemetry objeto.

Regras de colocação de wildcard

• Só é permitido um* por caminho de entrada ou saída.
• Devem * corresponder a um segmento completo (não a um segmento parcial como Sensor*).
• Podem * aparecer no início (*.Value), no meio (Sensors.*.Reading) ou no fim (Sensors.*) de um caminho.

Curingas de entrada múltipla

Quando uma regra tem múltiplas entradas com curingas, é * necessário capturar o mesmo segmento em todas as entradas. O tempo de execução resolve o * a partir da primeira entrada, depois procura caminhos correspondentes nas outras entradas.

Por exemplo, para fazer a média das leituras máximas e mínimas de cada sensor:

Dado este input:

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

As * capturas Temperature primeiro, por isso a regra procura tanto Temperature.Max como Temperature.Min. Depois captura Pressure e procura Pressure.Max e Pressure.Min. A saída é:

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

Se qualquer entrada não conseguir resolver para um segmento capturado (por exemplo, *.Mid.Avg quando o campo está aninhado de forma diferente), esse segmento é ignorado. Certifique-se de que os caminhos em todas as entradas refletem a estrutura real dos dados.

Anule um coringa para campos específicos

Podes combinar uma regra de wildcard com regras específicas. Regras específicas têm prioridade quando têm uma cobertura menor (menos segmentos correspondidos por *). Isto chama-se especialização.

A primeira regra aplica-se a todas as áreas. A segunda regra sobrepõe-se apenas para Pressure isso, porque Pressure.Max é mais específica do que *.Max (cobertura 0 vs. cobertura 1).

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

Uma saída vazia elimina o campo do resultado. Isto sobrepõe-se a qualquer regra de wildcard que de outra forma o incluiria.

Múltiplas regras nas mesmas entradas

Se duas regras tiverem a mesma ou superior cobertura, ambas se aplicam. Isto permite-lhe calcular múltiplos valores derivados das mesmas entradas:

Ambas as regras executam-se para cada segmento capturado, produzindo dois campos de saída por sensor.

Curingas em conjuntos de dados de contextualização

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

Isto copia todos os campos do assetMeta conjunto de dados para a Asset secção do resultado.

Conjuntos de dados de contextualização

Conjuntos de dados de contextualização permitem que os mapeamentos integrem dados extra de bases de dados externas. 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 detalhes sobre a configuração de conjuntos de dados de contextualização, veja Enriquecer dados usando fluxos de dados e Enriquecer com dados externos em grafos de fluxo de dados.

Conteúdo relacionado

Se chegou aqui à procura da sintaxe usada numa 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 num fluxo de dados.