字段计算

• 创建字段计算
• 类型
• 配置
  • 基本设置
  • 参数
  • 计算
  • 输出
    • 输出策略
• 调试
• 规则引擎集成
• 数据重新处理
• 滚动参数的内置方法
• 合并时间序列参数
• 导出/导入字段计算
• 管理字段计算
• 字段计算概览视频
• 反馈意见

字段计算可将原始数据实时转换为可执行化洞察。 字段计算可视为IoT实体的内置”逻辑层”。 不再仅存储原始数据，数据到达时即可自动生成高价值指标。

通过组合多源数据——如传入的时间序列、现有实体属性，乃至相关资产的数据——可在数据到达时执行自定义逻辑。 结果输出会自动存储为时间序列数据或属性，确保计算洞察可立即用于可视化、报表或进一步自动化。

为支持复杂工作流，字段计算执行可链式：一个字段的输出可自动触发另一个字段执行，从而逐步构建数据处理流水线。

字段计算可在系统中两个层级应用：

• 实体层级：在此层级，计算应用于单一特定实体——设备或资产。
• 配置文件层级：在设备配置或资产配置内定义字段计算时，该逻辑会由关联该配置文件的每个实体继承。

这种灵活性允许用户为每个实体定义独立计算，或对一组相似实体应用标准化逻辑，从而优化数据处理与管理。

除实时处理外，ThingsBoard支持字段计算的重新处理，可将相同计算逻辑应用于历史时间序列数据，并为所选时间范围生成缺失或更新结果。

创建字段计算

在设备、资产、设备配置或资产配置中创建字段计算的流程相同。

• 在左侧菜单中打开”字段计算”页面。
• 点击右上角”+“按钮。
• 在下拉菜单中选择创建新字段计算。

类型

ThingsBoard支持多种字段计算类型，各自针对特定任务场景：

• 
  简单字段计算

  基础算术表达式和标准函数。

• 
  脚本字段计算

  使用TBEL的复杂计算，支持返回多个值。

• 
  地理围栏字段计算

  确定实体相对于地理区域的位置，检测进入/退出事件，并生成通知。

• 
  传播字段计算

  根据关系方向和类型向关联实体传播或转换数据。

• 
  关联实体聚合字段计算

  从关联实体汇总最新数据（最小值、最大值、平均值、求和、计数等）。

• 
  时序数据聚合字段计算

  从当前实体汇总历史数据。

配置

基本设置

“基本设置”区域定义字段计算的基本配置：

• 标题 —— 描述字段计算用途的名称。
• 实体类型 —— 应用字段计算的目标实体或实体配置文件。
• 类型 —— 决定计算模型和可用配置块的字段计算类型。

参数

参数定义字段计算读取哪些数据并将其作为变量暴露给计算逻辑。每个参数映射到所选实体的特定数据源（属性或时间序列），可在简单表达式、TBEL脚本或其它字段计算类型中引用。

点击添加参数按钮并填写必填字段：

实体类型
定义数据读取来源：

• 当前实体 —— 应用字段计算的同一设备/资产（设备配置/资产配置）。
  若在设备配置或资产配置层级创建，则对关联该配置文件的每个实体执行计算。
• 另一个设备/资产 —— 特定引用实体
• 客户 —— 与实体关联的客户
• 当前租户 —— 租户实体
• 当前所有者 —— 当前实体的所有者
• 相关实体（适用于特定字段计算类型）—— 通过关系动态解析的实体

参数类型

字段计算支持以下参数类型：

Attribute

Latest telemetry

Time series rollingfor Script-based calculations and specific aggregation modes

使用存储为实体属性的静态或半静态数据。 示例：model、maxTemperature、safeZone、buildingId 配置： 参数类型：Attribute 选择作用域：Server、Client 或 Shared。 指定属性键。 设置参数名称，即脚本逻辑中使用的变量名。 可选设置属性的默认值。

使用指定时序键的最新遥测值。 示例：temperature、humidity、latitude、longitude 配置： 参数类型：Latest telemetry 指定时序键。 设置参数名称，即脚本逻辑中使用的变量名。 可选设置时序的默认值。

使用指定时间窗口内的历史时序数据进行趋势分析。 示例：speed、voltage 配置： 参数类型：Time series rolling 指定时序键。 设置参数名称，即脚本逻辑中使用的变量名。 定义数据采集时间窗口，确定用于计算的历史遥测时间范围。 设置可处理的最大数据点数（该设置由系统管理员在租户配置中配置。）

计算

字段计算根据所选类型支持多种计算模型。计算可定义为单一表达式、TBEL脚本、地理区域评估、向相关实体传播值或聚合。

更多能力与配置选项详见对应字段计算类型文档。

输出

无论类型如何，字段计算都会产生一个或多个输出值，随后按配置的输出策略存储为时间序列或属性并处理（立即或通过规则链）。

结果可存储为：

• 时间序列 —— 函数返回JSON对象或JSON对象数组，可带或不带时间戳，包含计算值。
• 属性 —— 函数返回不含时间戳信息的JSON对象，包含计算值。属性可存储在服务器或共享范围。

输出策略

输出策略定义字段计算结果的处理方式。支持两种策略：

• Process immediately（默认）— 立即处理并存储结果，不经过Rule Chain。
• Process via Rule Chains — 将结果传入实体的Default Rule Chain，进行额外处理逻辑。

调试

ThingsBoard提供内置工具，用于实时验证和排查字段计算问题。

启用调试模式 （*建议在开发时启用）

每个字段计算可切换至调试模式。启用后，ThingsBoard会记录每次执行的详细信息，包括触发执行的输入参数（如传入时间序列或属性更新）及计算结果或执行问题（脚本错误、缺失参数、无效值等）。

调试模式

启用调试模式可追踪与执行相关的事件、状态及潜在错误，便于开发和排障。

注意：调试模式可能迅速增加磁盘占用，因为所有调试事件都会存入数据库。 自ThingsBoard 3.9起，平台仅在创建后的前15分钟内存储完整调试事件，之后仅保留错误事件。

调试模式设置可组合使用或完全关闭。

查看调试事件

点击字段计算行中的事件图标查看记录的调试事件。

每个事件包括：

• 实体ID —— 执行字段计算的实体ID（目标实体）
• 消息ID —— 唯一执行标识
• 消息类型 —— 触发字段计算执行的内部请求类型
• 参数 —— 执行时使用的已解析参数值，包含时间戳（如有）
• 结果 —— 字段计算产生的输出
• 错误 —— 执行失败原因（执行失败时显示）

基于脚本的字段计算的测试模式

针对基于脚本的字段计算（如脚本、传播（计算结果模式）），ThingsBoard提供测试脚本函数（TBEL）模式，可在应用变更前使用真实输入数据验证执行。

此模式可：

• 使用相同输入数据重新运行计算
• 临时修改参数数据或脚本逻辑（不保存配置变更）
• 验证输出JSON结构和时间戳
• 查看脚本执行的准确输出
• 快速复现错误并修正逻辑

用法：

在事件行点击使用此消息测试运行测试函数。

• 左面板——脚本编辑器
  显示字段计算使用的TBEL calculate(ctx, …)函数。可直接在此窗口修改脚本。
• 右上面板——参数
  显示计算中使用的参数列表。可调整参数值、类型和时间戳以模拟不同输入数据。
• 右下面板——输出 显示脚本执行后的返回结果（或执行失败时的错误信息）。

流程：

• 更新脚本和/或参数值。
• 点击测试使用提供的输入执行函数。
• 在输出区域核对返回的JSON结构和值。
• 结果正确后点击保存保存变更。
• 如需，将变更应用到字段计算配置以激活更新后的逻辑。

规则引擎集成

字段计算与ThingsBoard规则引擎集成，即平台的消息路由与处理系统。 执行无缝接入数据工作流，在以下规则节点处理时间序列或属性时自动触发：

• 保存时间序列：新时间序列持久化时触发计算。
• 保存属性：客户端、共享或服务器端属性更新时触发计算。
• 字段计算：专用节点，用于手动调用字段评估或实现复杂链式逻辑。

数据重新处理

字段计算重新处理用于将字段计算逻辑应用到历史数据。 在修改现有计算或添加新字段，并希望变更不仅作用于新数据，也作用于已收集时间序列时尤为有用。

注意： 仅包含基于属性参数的字段计算无法重新处理。字段计算必须至少包含一个基于时间序列的参数，即”最新时间序列”或”时间序列滚动”数据。

关键功能

• 历史数据重算 —— 将更新后的逻辑应用于已收集的时间序列。
• 灵活时间范围 —— 为重新处理选择特定时间段。
• 以时间序列存储结果 —— 处理后的数据在ThingsBoard中保存为时间序列，可用于小部件、规则或分析。

配置方法

• 选择目标实体或配置文件，进入”字段计算“选项卡，创建新字段计算或选择需要历史时间序列重新处理的已有字段。
• 点击对应字段旁的”重新处理字段计算“图标。
• 在弹出窗口中定义要重新处理的时间序列时间区间。
• 点击”重新处理” —— 系统将按最新逻辑开始重算并更新历史时间序列数据。
• 重新处理完成后点击完成。

使用数据重新处理功能的示例

假设Smart Device实时发送温度与湿度数据。随后配置字段计算计算露点。 在时间序列小部件上可见，露点值仅在13:44:35之后出现——此前未执行该计算。

要重算历史时段（字段计算创建前）的露点，按以下步骤操作：

• 进入相应Smart Device的字段计算选项卡。点击所需字段所在行的重新处理字段计算图标。

• 在对话窗口中指定重新计算的时间间隔，然后点击重新处理。

• 流程完成后，点击完成。

结果是所选历史整个时段内会生成并存储dewPoint值。

任务管理器

任务管理器用于查看任务状态、跟踪进度、查看结果，以及定位数据处理过程中的错误。

滚动参数的内置方法

时间序列滚动参数支持用于计算的内置函数。这些函数接受可选的ignoreNaN布尔参数。

假设以下时间序列滚动参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "temperature": {
    "timeWindow": {
      "startTs": 1740643762896,
      "endTs": 1740644662896
    },
    "values": [
      { "ts": 1740644350000, "value": 72.32 },
      { "ts": 1740644360000, "value": 72.86 },
      { "ts": 1740644370000, "value": 73.58 },
      { "ts": 1740644380000, "value": "NaN" }
    ]
  }
}

用法和结果

1
2
3
4
5
6
7
var avgTemp = temperature.mean(); // Returns 72.92
var tempMax = temperature.max(); // Returns 73.58
var valueCount = temperature.count(); // Returns 3

var avgTempNaN = temperature.mean(false);  // Returns NaN
var tempMaxNaN = temperature.max(false);   // Returns NaN
var valueCountNaN = temperature.count(false); // Returns 4

适用场景

• 统计分析：计算均值、中位数和标准差用于趋势分析。
• 数据筛选：识别时间窗口内的最大最小值。
• 质量控制：用count() 和std() 检测缺失值或异常值。
• 能效监控：汇总一段时间内的功耗以评估能耗模式。

合并时间序列参数

时间序列滚动参数可合并以在多个数据集间对齐时间戳。 合并函数通过收集所有参数的时间戳并按这些时间戳合并值，将两个或多个滚动参数合并。 若某参数在某一时间戳无对应值，则使用该参数的前一个值；若无前值则赋NaN。 结果为新的滚动参数，包含时间窗口和按每个时间戳对应各参数值的数组。

参数

假设以下参数及其值：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "humidity": {
    "timeWindow": {
      "startTs": 1741356332086,
      "endTs": 1741357232086
    },
    "values": [{
      "ts": 1741356882759,
      "value": 43
    }, {
      "ts": 1741356918779,
      "value": 46
    }]
  },
  "pressure": {
    "timeWindow": {
      "startTs": 1741356332086,
      "endTs": 1741357232086
    },
    "values": [{
      "ts": 1741357047945,
      "value": 1023
    }, {
      "ts": 1741357056144,
      "value": 1026
    }, {
      "ts": 1741357147391,
      "value": 1025
    }]
  },
  "temperature": {
    "timeWindow": {
      "startTs": 1741356332086,
      "endTs": 1741357232086
    },
    "values": [{
      "ts": 1741356874943,
      "value": 76
    }, {
      "ts": 1741357063689,
      "value": 77
    }]
  }
}

用法：

1
var mergedData = temperature.merge(humidity, { ignoreNaN: false });

输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "mergedData": {
    "timeWindow": {
      "startTs": 1741356332086,
      "endTs": 1741357232086
    },
    "values": [{
      "ts": 1741356874943,
      "values": [76.0, "NaN"]
    }, {
      "ts": 1741356882759,
      "values": [76.0, 43.0]
    }, {
      "ts": 1741356918779,
      "values": [76.0, 46.0]
    }, {
      "ts": 1741357063689,
      "values": [77.0, 46.0]
    }]
  }
}

用法：

1
var mergedData = temperature.mergeAll([humidity, pressure], { ignoreNaN: true });

输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "mergedData": {
    "timeWindow": {
      "startTs": 1741356332086,
      "endTs": 1741357232086
    },
    "values": [{
      "ts": 1741357047945,
      "values": [76.0, 46.0, 1023.0]
    }, {
      "ts": 1741357056144,
      "values": [76.0, 46.0, 1026.0]
    }, {
      "ts": 1741357063689,
      "values": [77.0, 46.0, 1026.0]
    }, {
      "ts": 1741357147391,
      "values": [77.0, 46.0, 1025.0]
    }]
  }
}

适用场景

在多个传感器以不同间隔提供数据流时，合并time series arguments很有用。 通过对齐timestamps并填充缺失值，合并可实现：

• 传感器数据同步：对齐测量相关参数（如温湿度）的多个传感器读数。
• 异常检测：合并多源telemetry以识别系统性能不一致或偏差。
• 能耗分析：合并各设备的功耗数据以提供统一的能耗趋势视图。
• 预测性维护：合并振动、温度和运行状态数据以预测设备故障。

导出/导入字段计算

可将字段计算导出为JSON文件，并导入到同一或另一ThingsBoard实例。

导出字段计算

• 进入字段计算页面。
• 在对应字段计算行中点击导出按钮。

导入字段计算

可从JSON配置文件导入字段计算配置。 在实体或配置文件间迁移字段计算配置时尤其有用，可保证一致性并减少手动配置。

导入步骤：

• 进入字段计算页面。点击”+“图标按钮，从下拉菜单中选择导入字段计算。

• 在打开的窗口中，上传包含字段计算配置的JSON文件，然后点击导入。

• 在打开的对话框中，指定将应用字段计算的实体或配置文件。

• 如果参数有任何问题，它们将被高亮显示。

• 确保导入的字段正确应用并更新任何必要的参数。

• 点击添加完成导入。

• 您已导入字段计算配置。

注意：确保导入的字段正确应用并更新所需参数：

• 若引用实体为当前实体，不会报错。
• 若引用实体在tenant中不存在，将作为错误在使用的argument处高亮。
• 若引用实体为当前tenant且导入到另一tenant，将自动调整为新区tenant且无错误。

管理字段计算

在”字段计算”页面集中管理所有字段计算。

每个字段计算包含操作面板：

1. 复制 —— 复制配置以快速创建新字段计算。
2. 导出 —— 下载配置为JSON文件用于备份或迁移。
3. 事件 —— 查看执行事件，包括状态变更和错误。
4. 调试 —— 启用调试模式并查看详细执行数据。
5. 删除 —— 从系统中移除字段计算。

查看字段计算的详细信息

点击字段计算可查看其详情。

修改字段计算

修改字段计算时，点击进入详情视图，再点击橙色铅笔按钮。 完成修改后，点击橙色检查按钮应用更新。

字段计算概览视频

更习惯可视化学习？可观看此短视频快速了解ThingsBoard中的字段计算。 涵盖核心概念、支持的计算类型，以及实时处理和转换数据的实践示例。

反馈意见

欢迎在github为ThingsBoard加星。 如有疑问，请联系我们。