关联实体聚合从与目标实体相关的多个实体（设备、资产、客户或租户）收集最新遥测或属性值，应用一个或多个聚合函数，并将聚合结果存储到目标实体。
仅对直接（单层）关系进行聚合，确保实体选择可预期。
在需要从多实体计算“组级”指标时使用“Related entities aggregation”，例如：
- 车队/建筑仪表板：所有传感器平均温度、所有电表总功率、所有机器最大振动
- 运营KPI：活跃设备数、告警数、在线率
- 占用/存在追踪：统计处于某状态的设备数（如motion = true）
- 能耗与用量合计：多设备或区域的能耗总和
- 质量监控：组内最小/最大读数（如最低冷冻温度、最高湿度）
- 筛选聚合：仅对实体子集聚合（如仅“active”设备或超出阈值的读数）
配置
打开 创建字段计算 对话框并指定：
- 字段计算 title；
- 将应用字段计算的 entity或entity profile；
- 选择 “Related entities aggregation” 作为字段计算 type。
Aggregation path to related entities
ThingsBoard will collect data for aggregation from all entities that match the selected relationship direction and relationship type.
关系方向
定义读取数据的实体路径：
- 从上级到下级 — 从子实体聚合数据。
- 从下级到上级 — 从父实体聚合数据。
聚合仅适用于直接（单层）的关系，不会递归或多层遍历。
关系类型
定义目标实体与关联实体间的关系类型（如Contains、Manages或任意类型）。
定义将从哪些实体读取数据聚合，以及目标实体与其他实体之间的关系类型。
参数
Arguments定义从各关联实体获取的聚合数据。
点击 Add argument 并填写必填项：
- Argument type：Latest telemetry 或 Attribute
- Time series key / Attribute key：要读取的key
- Argument name：在metrics中使用的变量名
- Default value：数据缺失时的回退值
参数与配置详见 Arguments 章节。
Click Add argument (1) and fill in the required fields:
select the Argument type (2), specify the Time series key / Attribute key (3) to read data from, enter the Argument name (4) that will be used in the metrics, and set the Default value (5).
Then click Add (6).”
指标
定义应用于arguments指定数据的函数类型（聚合）以及存储聚合结果的key。
每个metric包含：
- Metric name：在目标实体上存储聚合结果的输出key名。
- Aggregation：Average / Min / Max / Sum / Count / Count unique
- Filter（可选）：聚合前包含/排除实体值
- Value source：使用直接argument值（Key）或函数结果（Function）
- Argument name：被聚合数据的 argument
筛选
筛选是返回 true/false 的函数，可使用任意已定义arguments。返回 true 时，实体值参与聚合；否则跳过。
示例：
1
return temperature > 10 && status == "active";
点击“添加指标”（1）并配置以下内容：指定“指标名称”（2）、选择“聚合类型”（3）、选择是否启用“筛选”（4）、选择“值来源（Key或Function）”（5）、并输入将用作数据源的“argument名称”（6）。
然后点击“添加”（7）。
去重复间隔
去重复间隔限制频繁更新时聚合的执行频率。
工作原理：
- 第一个更新触发一次聚合
- 在间隔内到达的其他更新不会再次触发聚合
- 间隔结束后，使用最新数据再次运行聚合
遥测数据聚合的最短时间间隔：10秒。
这可防止过度重复处理并减少高频更新环境中的系统负载。
“去重复间隔”是两次聚合之间的最短时间间隔。它限制了字段计算在频繁接收更新时重新聚合的次数。
输出
计算结果以 time series 或 attribute 形式存储。
如需要，可设置Decimals进行舍入。
[仅适用于Time series]
启用 Use latest timestamp 以使用最新argument时间戳而非服务器时间存储结果。
输出类型与处理策略详见 Output 章节。
示例：汇总多个子设备的温度值
场景
多台温度传感器设备安装在 Building A 中，并持续发布遥测值。
目标
从与Building A相关联的所有传感器收集温度遥测，并计算：
- avgTemperature — 建筑的平均温度
- maxTemperature — 建筑的最高温度
将两个值作为“遥测”存储在“Building A”资产上。
你将配置的内容
你将在Building A资产上应用一个“聚合”字段计算来执行以下操作：
- 从相关联的设备（子传感器）读取最新温度值
- 计算平均值和最大值
- 将结果作为遥测写入Building A
字段计算配置
下载“关联实体聚合”字段计算配置 (JSON).
配置步骤
1. 导入演示设备
导入发布 temperature 遥测数据的多个智能设备。
- 下载CSV文件：device-data-with-temperature-telemetry.csv
- 转到“设备”并导入 CSV文件
CSV包含：
- 名称： Smart Device 1
- 类型： sensor
- 时间序列： temperature
关于CSV的重要说明： temperature 键的列类型必须设置为“时间序列”。
转到“设备”并从CSV文件“导入”设备配置。
名称：Smart Device 1
类型：sensor
时间序列：temperature
已导入发布温度遥测数据的智能设备。
2. 导入演示资产
导入代表建筑的资产。
- 下载CSV文件：building-asset-data.csv
- 转到“资产”并导入 CSV文件。
CSV包含：
- 名称： Building A
- 类型： building
导入演示资产Building A。
3. 为资产与设备间创建关系
为Building A与所有智能传感器创建关系：
- 关系方向： 从（设备 ⇾ Building A）
- 关系类型： 管理
这些关系定义了将收集其遥测数据的相关联实体集。
为Building A与所有智能传感器创建关系：关系方向：从（设备 ⇾ Building A）, 关系类型：管理
4. 将字段计算应用于资产
将“相关联实体聚合”字段计算应用于“Building A”资产。
- 下载字段计算配置文件.
- 转到“字段计算”标签页并导入配置。
此字段将：
- 从所有子设备读取最新温度值
- 计算平均值/最大值
- 将结果存储在Building A上
转到“字段计算”标签页并导入字段计算配置。
将字段计算应用于“building”资产配置。
向相关联实体的传播路径：关系方向: 从上级到下级；关系类型: 管理。
参数设置：
- 参数类型： 最新遥测
- 时间序列键： temperature
- 参数名称： temperature
- 默认值： 0。
第一个指标设置：
- 指标名称： avgTemperature
- 聚合： 平均
- 值来源： key
- 参数名称： temperature。
第二个指标设置：
- 指标名称： maxTemperature
- 聚合： 最大
- 值来源： key
- 参数名称： temperature。
去重复间隔：10秒。
输出值将存储为遥测。点击“添加”保存字段计算。
(可选) 启用Debug模式并使用“事件”图标检查执行事件。
结果
Building A资产存储聚合的遥测，比如：
- avgTemperature — 所有传感器的平均温度
- maxTemperature — 任一传感器报告的最高温度
示例：
1
{ "avgTemperature": 22.7, "maxTemperature": 25.1 }
Building A资产存储的聚合遥测值，例如：
- avgTemperature — 所有传感器的平均温度
- maxTemperature — 其中一个传感器测量的最高温度