📚 课程目录第4章遥测数据模型

4. 遥测数据模型：遥测键值对结构、时间戳处理、数据类型与序列化

遥测（Telemetry）是 ThingsBoard 平台中设备上报的时序数据核心。与属性（Attributes）不同，遥测数据天然带有时间戳，用于记录设备在某一时刻的状态或测量值。本章将深入解析遥测数据模型的关键要素：键值对结构、时间戳处理机制、支持的数据类型以及数据序列化格式。

ThingsBoard 的遥测数据采用 键值对（Key-Value） 结构，每个遥测点由一个唯一的键（Key）和一个对应的值（Value）组成。键是字符串，用于标识遥测指标（如 temperature、humidity）；值可以是多种数据类型。

  核心原则： 每个遥测消息可以包含多个键值对，但所有键值对共享同一个时间戳。如果需要不同时间戳的数据，必须分开发送。

典型的遥测数据载荷（JSON 格式）示例如下：

{
  "temperature": 23.5,
  "humidity": 68.2,
  "status": "running",
  "location": {
    "lat": 39.9042,
    "lng": 116.4074
  }
}

在此示例中，temperature 和 humidity 是数值类型，status 是字符串类型，location 是嵌套的 JSON 对象。

时间戳是遥测数据与属性数据最本质的区别。ThingsBoard 支持两种时间戳传递方式：

方式	说明	适用场景
服务端时间戳	设备不携带时间戳，由 ThingsBoard 服务端在接收数据时自动添加当前时间。	实时数据上报，设备时钟不可靠或无需历史回填。
客户端时间戳	设备在遥测消息中显式携带 `ts` 字段，指定数据采集的原始时间。	离线数据补传、历史数据回放、设备本地缓存后批量上报。

客户端时间戳的完整载荷格式：

{
  "ts": 1712345678000,
  "values": {
    "temperature": 23.5,
    "humidity": 68.2
  }
}

注意： 时间戳必须为毫秒级。如果使用秒级时间戳（10 位数字），ThingsBoard 会将其解析为 1970 年附近的时间，导致数据错乱。建议在设备端统一使用毫秒级时间戳。

ThingsBoard 遥测支持以下四种核心数据类型：

数据类型	JSON 示例	存储与查询特性
数值（Number）	`23.5`, `100`	支持范围查询、聚合函数（AVG、MAX、MIN、SUM）、数值比较。
字符串（String）	`"running"`, `"error_001"`	支持精确匹配、模糊查询（LIKE），不支持数值运算。
布尔值（Boolean）	`true`, `false`	支持逻辑判断，常用于开关状态、告警标志。
JSON 对象	`{"lat": 39.9, "lng": 116.4}`	支持嵌套结构，可存储复杂数据（如 GPS 坐标、设备配置快照）。

最佳实践： 对于 GPS 坐标、多维传感器数据等复合信息，优先使用 JSON 对象类型，避免拆分为多个独立键值对，以减少网络开销并保持数据语义完整性。

ThingsBoard 默认使用 JSON 作为遥测数据的序列化格式。此外，平台也支持 Protobuf（Protocol Buffers）用于高性能场景。

序列化格式	优点	缺点	推荐场景
JSON	人类可读、调试方便、生态广泛	数据冗余大、解析性能中等	开发调试、低频上报、小数据量
Protobuf	数据体积小、解析速度快、带宽占用低	需预定义 schema、调试困难	高频上报、低带宽网络、大规模部署

以下为同一组遥测数据在两种格式下的体积对比：

// JSON 格式（约 85 字节）
{"temperature":23.5,"humidity":68.2,"status":"running"}

// Protobuf 格式（约 30 字节，基于预定义 schema）
// 二进制编码，不可直接阅读

下图展示了遥测数据从设备端到 ThingsBoard 存储层的完整模型架构：

在实际项目中，设备上报遥测数据时面临时间戳选择问题。以下流程图帮助决策：

键命名规范： 使用小写字母加下划线（snake_case），如 water_level、motor_speed，避免特殊字符和空格。
避免键名过长： 键名会占用存储空间和网络带宽，建议控制在 20 个字符以内。
数据类型一致性： 同一个键在不同时间点的数据类型应保持一致。例如 temperature 始终为数值，不要某次上报字符串 "23.5"，下次上报数值 23.5。
JSON 对象扁平化： 如果 JSON 对象嵌套过深（超过 3 层），建议拆分为多个独立键值对，以提升查询性能。

性能提示： 对于高频遥测（每秒多次上报），建议使用 Protobuf 序列化并启用批量上报（一次消息包含多条遥测记录），可显著降低带宽消耗和服务端解析压力。