数据模板

用户通过 NeuronEX 进行数据分析处理后，使用各种动作 (Sink) 可以往不同的系统发送数据分析结果。针对同样的分析结果，不同的动作 (Sink) 需要的格式可能未必一样。

比如，在某场景中，当发现某设备温度过高的时候，需要向云端某 REST 服务发送一个请求，同时在本地需要通过 MQTT 协议往设备发送一个控制命令，这两者需要的数据格式可能并不一样，因此，需要对来自于分析的结果进行「二次处理」后，才可以往不同的目标发送针对数据。本文将介绍如何利用 Sink 中的数据模版 (Data Template) 来实现对分析结果的「二次处理」。

Golang 模版介绍

Golang 模版将一段逻辑应用到数据上，然后按照用户指定的逻辑对数据进行格式化输出。NeuronEX 使用了 Golang template（模版）对分析结果实现「二次处理」，请参考以下来自于 Golang 的官方介绍。

模版是通过将其应用到一个数据结构上来执行的。模版中的注释 (Annotations) 指的是数据结构中的元素（典型的为结构体中的一个字段，或者 map 中的一个 key），注释用于控制执行、并获取用于显示的值。模版的执行会迭代数据结构并设置游标，通过符号「.」来表示，在执行过程中指向数据结构中的当前位置。
模版的输入文本可以为 UTF-8 编码的任意文本。「动作 (Actions)」 -- 数据求值或者控制结构 - 是通过 " 和 " 来界定的；所有在动作之外的文本会被保持原样到输出，除了 raw strings，动作不可跨行（注释除外）。

基础模板语法

如果 sendSingle 为 true，则数据模板将针对某一条记录执行操作；否则，它将对整个记录数组执行操作。典型的数据模板是：

例如，我们的目标输入为

[]map[string]interface{}{{
    "ab" : "hello1",
},{
    "ab" : "hello2",
}}

在 sendSingle=true 模式下：

打印整个记录

"dataTemplate": "{\"content\":{{json .}}}",

打印 ab 字段

"dataTemplate": "{\"content\":{{.ab}}}",

如果 ab 字段是字符串，请添加引号

"dataTemplate": "{\"content\":\"{{.ab}}\"}",

在 sendSingle=false 模式下：

打印出整个记录数组

"dataTemplate": "{\"content\":{{json .}}}",

打印出第一条记录

"dataTemplate": "{\"content\":{{json (index . 0)}}}",

打印出第一个记录的字段 ab

"dataTemplate": "{\"content\":{{index . 0 \"ab\"}}}",

将数组中每个记录的字段 ab 打印为 html 格式

"dataTemplate": "<div>results</div><ul>{{range .}}<li>{{.ab}}</li>{{end}}</ul>",

可以自定义动作以支持不同种类的输出，有关更多详细信息，请参见扩展。

模版中支持的函数

用户可通过模板函数，对数据进行各种转换，包括但不限于格式转换，数学计算和编码等。eKuiper 中支持的模板函数包括以下几类：

Go 语言内置模板函数。
来自 sprig library 的丰富的扩展函数集。
NeuronEX 扩展的函数。

动作 (Actions)

Golang 模版提供了一些内置的动作，可以让用户写各种控制语句，用于提取内容。比如，

根据判断条件来输出不同的内容

{{if pipeline}} T1 {{else}} T0 {{end}}

循环遍历数据，并进行处理

{{range pipeline}} T1 {{else}} T0 {{end}}

动作是用 {{}} 界定的，在 NeuronEX 的数据模版使用过程中，由于输出一般也是 JSON 格式，而 JSON 格式是用 {} 来界定，因此读者在不太熟悉使用的时候，在使用 NeuronEX 的数据模版的功能会觉得比较难以理解。比如以下的例子中，

{{if pipeline}} {"field1": true} {{else}}  {"field1": false} {{end}}

上述表达式的意思如下（请注意动作的界定符和 JSON 的界定符）：

如果满足了条件 pipeline，则输出 JSON 字符串 {"field1": true}
否则输出 JSON 字符串 {"field1": false}

NeuronEX sink 数据格式

Golang 的模版可以作用于各种数据结构，比如 map、切片 (slice)，通道等，而 NeuronEX 的 sink 中的数据模版得到的数据类型是固定的，是一个包含了 Golang map 切片的数据类型，如下所示。

[]map[string]interface{}

切片 (slice) 数据按条发送

流入 sink 的数据是一个 map[string]interface{} 切片的数据结构，但是用户往目标 sink 发送数据的时候，可能是需要单条的数据，而不是所有的数据，比如：

json

[
  {"device_id":"1","t_av":36.25,"t_count":4,"t_max":80,"t_min":10},
  {"device_id":"2","t_av":27,"t_count":4,"t_max":45,"t_min":12}
]

在发送到 sink 的时候，希望每条数据分开发送，首先需要将 sink 的 sendSingle 设置为 true，然后使用数据模版：{{json .}}，完整配置如下，用户可以将其拷贝到某 sink 配置的最后。

json

 ...
 "sendSingle": true,
 "dataTemplate": "{{toJson .}}"

将 sendSingle 设置为 true后，NeuronEX 把传递给 sink 的 []map[string]interface{} 数据类型进行遍历处理，对于遍历过程中的每一条数据都会应用用户指定的数据模版
toJson 是 NeuronEX 提供的函数，可以将传入的参数转化为 JSON 字符串输出，对于遍历到的每一条数据，将 map 中的内容转换为 JSON 字符串

Golang 还内置提供了一些函数，用户可以参考更多 Golang 内置提供的函数来获取更多函数信息。

数据内容转换

还是针对上述例子，需要对返回的 t_av（平均温度）做一些转换，转换的基本要求就是根据不同的平均温度，加入不同的描述文字，用于目标 sink 中的处理。规则如下，

当温度小于 30，描述字段为「Current temperature is$t_av, it's normal.」
当温度大于 30，描述字段为「Current temperature is$t_av, it's high.」

假设目标 sink 还是需要 JSON 数据，该数据模版的内容如下，

json

...
"dataTemplate": "{\"device_id\": {{.device_id}}, \"description\": \"{{if lt .t_av 30.0}}Current temperature is {{.t_av}}, it's normal.\"{{else if ge .t_av 30.0}}Current temperature is {{.t_av}}, it's high.\"{{end}}}"
"sendSingle": true,

在上述的数据模版中，使用了 {{if pipeline}} T1 {{else if pipeline}} T0 {{end}} 的内置动作，看上去比较复杂，稍微调整一下，去掉转义并加入缩进后排版如下（注意：在生成 NeuronEX 规则的时候，不能传入以下优化后排版的规则）。

{"device_id": {{.device_id}}, "description": "
  {{if lt .t_av 30.0}}
    Current temperature is {{.t_av}}, it's normal."
  {{else if ge .t_av 30.0}}
    Current temperature is {{.t_av}}, it's high."
  {{end}}
}

使用了 Golang 内置的二元比较函数，

lt：小于
ge：大于等于

值得注意的是，在 lt 和 ge 函数中，第二个参数值的类型应该与 map 中的数据实际的数据类型一致，否则会出错。如在上述的例子中，温度大于 30 的情况，因为 map 中实际平均数的类型为 float，因此第二个参数的值需传入 30.0，而不是 30。

另外，模版还是应用到切片中每条记录上，所以还是需要将 sendSingle 属性设置为 true。最终该数据模版针对上述数据产生的内容如下，

json

{"device_id": 1, "description": "Current temperature is 36.25, it's high."}
{"device_id": 2, "description": "Current temperature is 27, it's normal."}

数据遍历

通过给 sink 的 sendSingle 属性设置为 true ，可以实现把传递给 sink 的切片数据进行遍历。在此处，我们将介绍一些更为复杂的例子，比如在 sink 的结果中，包含了嵌套的数组类型的数据，如何通过在数据模版中提供的遍历功能，自己来实现遍历。

假设流入 sink 中的数据内容如下所示，

json

{"device_id":"1", 
 "values": [
  {"temperature": 10.5},
  {"temperature": 20.3},
  {"temperature": 30.3}
 ]
}

需求为，

当发现 "values" 数组中某个 temperature 值小于等于 25 的时候，增加一个名为 description 的属性，将其值设置为 fine。
当发现 "values" 数组中某个 temperature 值大于 25 的时候，增加一个名为 description 的属性，将其值设置为 high。

json

"sendSingle": true,
"dataTemplate": "{{$len := len .values}} {{$loopsize := add $len -1}} {\"device_id\": \"{{.device_id}}\", \"description\": [{{range $index, $ele := .values}} {{if le .temperature 25.0}}\"fine\"{{else if gt .temperature 25.0}}\"high\"{{end}} {{if eq $loopsize $index}}]{{else}},{{end}}{{end}}}"

该数据模板比较复杂，解释如下，

{{$len := len .values}} {{$loopsize := add $len -1}}，这一段执行了两个表达式，第一个 len 函数取得数据中 values 的长度，第二个 add 将其值减 1 并赋值到变量 loopsize：由于 Golang 的表达式中目前还不支持直接将数值减 1 的操作， add 是 eKuiper 为实现该功能而扩展的函数。

{\"device_id\": \"{{.device_id}}\", \"description\": [ 这一段模版在作用到样例数据后，生成了 JSON 串 {"device_id": "1", "description": [

{{range $index, $ele := .values}} {{if le .temperature 25.0}}\"fine\"{{else if gt .temperature 25.0}}\"high\"{{end}} {{if eq $loopsize $index}}]{{else}},{{end}}{{end}} ，这一段模版看起来比较复杂，但是如果把它调整一下，去掉转义并加入缩进后排版如下，看起来可能会更加清晰（注意：在生成 NeuronEX 规则的时候，不能传入以下优化后排版的规则）。

{{range $index, $ele := .values}} 
  {{if le .temperature 25.0}}
    "fine"
  {{else if gt .temperature 25.0}}
    "high"
  {{end}} 
  {{if eq $loopsize $index}}
    ]
  {{else}}
    ,
  {{end}}
{{end}}

第一个条件判断生成是 fine 或者 high；第二个条件判断是生成分隔数组的 , 还是数组结尾的 ]。

另外，模版还是应用到切片中每条记录上，所以还是需要将 sendSingle 属性设置为 true。最终该数据模版针对上述数据产生的内容如下，

json

  {"device_id": "1", "description": [ "fine" , "fine" , "high" ]}

使用 AI 辅助生成

eKuiper 的模板语法与 Go 语言相同，因此可以方便地通过 AI 辅助生成数据模版。我们可以使用如下提示词发送给大语言模型，来辅助生成数据模版：

使用 Golang 的 text/template 以及 sprig 库将数据
{
    "timestamp": 1650006388943,
    "node": "modbus",
    "group": "grp",
    "values": {
        "tag1": 123,
        "tag2": 234
    }
}
转换成
{
  "timestamp": 1650006388943,
  "node": "modbus",
  "group": "grp",
  "tags": [{
        "name": "tag1",
        "value": 123
      },{
        "name": "tag2",
        "value": 234
      }
  ]
}

获取到的模板结果结果大致为：

json

{"timestamp": {{.timestamp}},"node": "{{ .node }}","group": "{{ .group }}","tags": [{{ range $key, $value := .values }}{{ if $key }},{ "name": "{{ $key }}", "value": {{ $value }} }{{ else }}{ "name": "{{ $key }}", "value": {{ $value }} }{{ end }}{{ end }}]}

使用规则调试功能，测试发现转换正常：

alt text

通过把输入和输出模板发送给大语言模型，即使不熟悉 Golang 模版语法，也可以方便地实现数据转换。

总结

通过 NeuronEX 提供的数据模版功能可以实现对分析结果的二次处理，以满足不同的 sink 目标的需求。但由于 Golang 模版本身的限制，较难实现较复杂的数据转换。目前建议用户可以通过数据模版来实现一些较为简单的数据的转换；如果用户需要对数据进行比较复杂的处理，并且自己扩展了 sink 的情况下，可以在 sink 的实现中直接进行处理。

Modbus RTU

Modbus TCP

Inovance Modbus TCP

OPC UA

OPC DA

Mitsubishi 3E

Siemens S7 ISO TCP

Siemens MPI

Omron FINS TCP

Omron FINS UDP

Beckhoff ADS

IEC60870-5-104

IEC61850

DL/T645-2007

BACnet/IP

Panasonic Mewtocol

SECS GEM HSMS

CODESYS V3

MQTT 插件

AWS IoT

Azure IoT

Sparkplug B 插件

数据表

函数

数据模板 ​

Golang 模版介绍 ​

基础模板语法 ​

模版中支持的函数 ​

动作 (Actions) ​

NeuronEX sink 数据格式 ​

切片 (slice) 数据按条发送 ​

数据内容转换 ​

数据遍历 ​

使用 AI 辅助生成 ​

总结 ​

数据模板

Golang 模版介绍

基础模板语法

模版中支持的函数

动作 (Actions)

NeuronEX sink 数据格式

切片 (slice) 数据按条发送

数据内容转换

数据遍历

使用 AI 辅助生成

总结