3.2 属性

属性定义了元素的可测量特性。它是物理资产行为与 TDengine TSDB 中存储数据之间的桥梁——将原始数值转化为有名称、有类型、有物理单位的工程量。

3.2.1 什么是属性

属性是元素的一个命名特性，用于保存或引用某个值。对于泵元素，属性可能包括流量、出口压力、电机温度和运行状态；对于智能电表，属性可能包括电流、电压、功率和设备 ID。

属性为原始数据赋予了上下文。用户和应用程序无需通过技术字段名查询数据库列，而是可以在清晰的资产层次结构中，通过有意义的属性名来引用数据。

3.2.2 数据引用类型

数据引用类型决定了属性值的来源。共有四种类型：

3.2.2.1 指标

引用 TDengine TSDB 表中的指标列（时序测量列）。属性值随新数据写入而实时更新。适用于随时间变化的值，如温度、压力、流量、电流、电压等。

数据引用设置的格式为：

连接名/数据库名/表名/列名

示例：TDengine/idmp_sample_utility/em-12/current

如果采集的指标还带有数据质量且与属性值存在同一张表，则数据引用设置还可以带上数据质量列的列名。格式为：

连接名/数据库名/表名/列名:质量列名

示例：TDengine/idmp_sample_utility/em-12/current:quality

备注

质量列的数据类型必须是 INT。

引用外部指标： 数据引用类型选择指标，在数据引用设置中选择已创建的 MySQL、PostgreSQL 或 InfluxDB 连接，再选择数据库、表和值列；PostgreSQL 还需选择 Schema。点击检查验证后保存。外部指标通过 TDengine 虚拟表读取，无需先将指标数据复制到 TDengine。

外部连接绑定的 TDengine 连接须与属性虚拟表所在的连接一致。MySQL、PostgreSQL 源表需包含唯一的时间戳类型主键列；InfluxDB 使用 time 列。当前外部指标引用暂不支持筛选条件。

3.2.2.2 标签

引用 TDengine TSDB 表中的标签值。标签是附加在表上的静态元数据字段（如设备 ID、位置或安装楼层）。适用于值来源于 TSDB 标签而非时序列的属性。

格式与指标相同：

连接名/数据库名/表名/标签名

示例：TDengine/idmp_sample_utility/em-17/location

引用外部标签： 数据引用类型选择标签，在数据引用设置中选择 MySQL、PostgreSQL 或 InfluxDB 连接，以及数据库、表和取值列；PostgreSQL 还需选择 Schema。外部标签可读取普通列，适用于设备名称、所属区域等元数据。

• 取值方式：选择唯一一行时，查询必须恰好返回一行；选择按时间取最新一行时，还需指定时间列，最新时间存在多行并列时检查失败。
• 筛选条件：点击添加条件，填写列名、值类型和条件值。当前支持等值条件，最多 16 条，可用 AND 或 OR 连接；AND 优先于 OR。
• 自动同步：默认开启。IDMP 定期读取外部值并更新 TDengine 中的本地标签；关闭后不再定期更新。查询无结果或结果为 NULL 时，优先使用属性配置的默认值更新本地标签；未配置默认值时，保留上次成功值。连接或查询执行失败时仍保留上次成功值，不使用默认值回退。

点击检查确认取值有效后保存。连接配置参见外部数据源连接。

备注

在外部标签的数据引用设置中，选择 SQL 查询方式可编辑只读查询，支持 IN、BETWEEN、CASE、EXISTS 等常用表达式。查询结果须为单行单列的非 NULL 值；无结果或结果为 NULL 时，可使用已配置的默认值回退，默认值须符合属性的数据类型及取值约束，否则检查或同步失败。WHERE 条件可引用同一元素的静态属性，详见下方属性模板示例。

3.2.2.3 公式

计算型属性，其值由引用同一元素其他属性的表达式推导得出。表达式会被转换为 TDengine SQL 表达式，并在 TDengine TSDB 上执行。输出必须为数值类型。

示例表达式：

log(current) * voltage + 10

可使用特殊替换参数 TIME，它会被替换为当前本地时间对应的毫秒数。您可以在表达式编辑器中点击评估，在保存前测试并验证公式。完整的表达式编辑器说明请参见 3.2.10 节。

备注

公式属性只能引用同一元素的属性。如需使用其他元素的值，请在当前元素上新增一个属性，使其指向相同的数据源。

引用的属性时间戳不对齐时必须使用 FILL_FORWARD

公式引用的多个属性若时间戳不对齐（各属性的数据点并非写入在同一时刻），则每个时间戳上只有部分属性有值、其余为 NULL，而 NULL 参与任何运算都会使整个公式的结果变为 NULL。此时必须为引用的属性包裹 FILL_FORWARD() 函数，将空值填充为该列上一个非空值，例如：fill_forward(current) * fill_forward(voltage) + 10。

FILL_FORWARD 函数的详细说明请参阅 TDengine 官方文档。

3.2.2.4 字符串构建器

与公式类似，但输出为字符串。输入可以是当前元素的任意属性（不限于数值类型）。常用函数包括：

• CONCAT(...) — 拼接多个字符串
• SUBSTR(str, start, length) — 截取子字符串
• CAST(value AS varchar) — 将非字符串类型转换为字符串

除 TIME 外，字符串构建器还支持更多替换参数，例如当前元素名、当前属性名和模板名。

示例表达式：

CONCAT('voltage of device ', ${attributes['Device ID']}, ' is ', CAST(${attributes['Voltage']} AS varchar), 'V')

备注

不能使用加号拼接字符串，请使用 CONCAT() 函数。CONCAT() 的每个参数都必须是字符串类型，请先使用 CAST() 将数值属性转换为字符串再传入 CONCAT()。

3.2.3 属性特性

每个属性都具有以下可配置特性：

3.2.3.1 基础字段

特性	说明
名称	属性在其元素内的唯一名称
描述	对该属性所测量或代表内容的可读说明
类别	用于在属性选项卡中对属性进行分组和筛选的一个或多个标签
值类型	值的数据类型，分为三类。基础类型：Float、Double、Int、IntUnsigned、BigInt、BigIntUnsigned、TinyInt、TinyIntUnsigned、SmallInt、SmallIntUnsigned、Bool、Nchar、Varchar、Timestamp、Decimal（需要 TDengine TSDB 版本 3.4.1.1 及以上，且数据引用类型必须为指标）。枚举类型：从系统中已定义的枚举类型中选择，属性值限定为该枚举的预定义选项。对象类型：File（文件）、Video（视频）、Attribute（属性引用）、Element（元素引用）。
默认值	当数据源无可用数据时返回的值
计量单位分类	物理量类别（如电流、温度、压力）。选择计量单位分类后，默认计量单位和显示计量单位的可用选项会相应筛选。
默认计量单位	属性值存储时使用的单位（如安培、°C、bar）
显示计量单位	在面板和仪表板中显示值时使用的单位，可以与默认计量单位不同——IDMP 会自动进行换算。
显示精度	正数表示小数点后显示数字位数，负数代表显示有效数字位数。
数据引用类型	属性值的来源：指标、标签、公式、字符串构建器或无（参见 3.2.2）
数据引用设置	选择来源连接、数据库、表和列。TDengine 原生引用格式为 连接名/数据库名/表名/列名，可选在列名后追加 :质量列名；外部连接还可配置 Schema、标签取值方式和筛选条件（见 3.2.2）。
路径	属性在资产模型中的完整路径（只读，自动生成）

命名规则

属性名称必须满足以下规则（属性与属性模板遵循相同的规则）：

• 名称不能为空，长度不能超过 255 个字符。
• 名称不能包含特殊字符 $、{、}（这些字符与替换参数 ${...} 的语法冲突）。
• 名称在同一元素（或同一元素模板）内必须唯一；同一父属性下的子属性、特性的名称也必须唯一。

不满足规则时无法保存，系统会提示相应错误。此外，描述的长度不能超过 2048 个字符。

3.2.3.2 极限值配置

为属性定义运行阈值。每个极限值有名称和数值：

极限值	含义
最小值	物理上可能或可接受的最低值
低低限	低低报警阈值——严重低值状态
低限	低报警阈值——警告低值状态
目标值	期望的设定点或正常运行值
高限	高报警阈值——警告高值状态
高高限	高高报警阈值——严重高值状态
最大值	物理上可能或可接受的最高值

每个极限值还有一个可选的属性字段——您可以将极限值关联到另一个属性而非固定数值，从而实现基于实时状态动态变化的极限值。

3.2.3.3 预测配置

为该属性配置基于 AI 的预测：

选项	说明
TDgpt	使用 TDengine 内置的时序预测引擎（TDgpt）预测未来值
外部	通过已配置的端点连接外部预测服务
无	不启用预测（默认）

3.2.3.4 附加特性

用于存储属性自定义元数据的自由键值对（如仪表标签、校准日期、传感器型号）。点击 + 添加新条目。

3.2.3.5 配置标志

标志	说明
常量	将该属性标记为常量——其值不随时间变化
隐藏	在默认属性列表中隐藏该属性。隐藏属性仅在启用显示隐藏属性开关时可见。
不包含	将该属性排除在分析和 AI 生成洞察之外

3.2.4 浏览属性

查看某个元素的属性：

1. 在元素树中选中该元素。
2. 在元素详情面板中点击属性选项卡。

属性列表显示：名称、描述、当前值、值类型、数据引用类型、最后更新时间和数据引用设置。

使用类别下拉框按类别筛选。开启显示隐藏属性可查看标记为隐藏的属性。

点击任意属性名称可打开其详情视图。

3.2.5 创建属性

为元素新增属性：

1. 选中元素并点击属性选项卡。
2. 点击工具栏中的 + 图标（属性选项卡右上角）。
3. 填写属性表单：
   • 输入名称和描述。
   • 选择值类型，如需要可设置默认值。
   • 选择计量单位分类，然后选择默认计量单位和显示计量单位。
   • 设置显示精度。
   • 选择数据引用类型并输入数据引用设置路径。
   • 可选择展开并配置极限值配置、预测配置和附加特性。
   • 根据需要设置配置标志（隐藏、不包含）。
4. 点击保存。

3.2.6 编辑属性

编辑属性有两种方式：

3.2.6.1 方式一：从属性详情视图编辑

1. 点击列表中的属性名称，打开其详情视图。
2. 点击工具栏中的编辑图标（铅笔）。
3. 修改所需字段后点击保存。

3.2.6.2 方式二：从属性列表的 ⋮ 菜单编辑

1. 在属性列表中，点击属性行上的 ⋮ 菜单。
2. 选择编辑。
3. 修改所需字段后点击保存。

3.2.7 删除属性

删除属性有两种方式：

3.2.7.1 方式一：从属性详情视图删除

1. 点击属性名称，打开其详情视图。
2. 点击右上角工具栏中的删除图标（垃圾桶）。
3. 确认删除。

3.2.7.2 方式二：从属性列表的 ⋮ 菜单删除

1. 在属性列表中，点击属性行上的 ⋮ 菜单。
2. 选择删除并确认。

注意

删除属性会从 TDengine IDMP 中移除其配置及所有关联元数据。TDengine TSDB 中的底层时序数据不受影响。引用了被删除属性的仪表板、分析或事件规则可能停止正常工作，需要相应更新。

3.2.8 其他属性操作

属性列表中的 ⋮ 菜单还提供以下操作：

操作	说明
查看	打开属性详情视图
复制	复制属性配置。复制的属性可粘贴为同一元素或其他元素上的新属性。
上移 / 下移	在列表中调整属性顺序
添加数据条目	指标属性特有操作，手动录入一个测点，录入的数据将插入到属性引用的 TSDB 表中
添加到趋势图	快速将该属性添加到新的趋势图面板
历史值	查看该属性的历史时序数据

3.2.9 子属性

属性可以挂载子属性——附属于父属性的下级属性，用于把一组相关信息挂在同一个父属性下统一管理。子属性分为两类：

类型	说明
一般子属性	不配置数据引用的子属性。系统会将其自动物化为元素虚拟表上的标签列（自动创建，无需手动配置数据引用），因此一般子属性可以像普通属性一样在表达式和面板中被引用。
数据引用子属性	配置了数据引用的子属性，例如公式引用。仅在无模板元素的自定义属性和属性模板上可用。

KPI 属性的子属性由系统按 KPI 定义自动生成并维护（参见 3.2.12 KPI 属性），无需手动添加。

3.2.9.1 管理子属性

子属性在属性的创建/编辑表单中的子属性折叠面板内管理：

1. 打开属性的创建或编辑表单。
2. 展开子属性面板，表格中列出已有子属性的名称、描述、数据引用类型、数据引用设置、值类型和显示值。
3. 点击面板底部的 + 打开子属性表单，填写字段后保存，子属性即加入列表。
4. 点击子属性行的 ⋮ 菜单可编辑或删除该子属性。
5. 点击属性表单的保存，子属性随父属性一并保存。

3.2.9.2 子属性的使用约束

约束	说明
不允许嵌套	子属性下不能再添加子属性。
不支持特性	子属性不能配置极限值、预测等特性。
值类型限制	子属性的值类型不提供 KPI 类型。
命名唯一	同一父属性下的子属性名称必须唯一（命名规则参见 3.2.3.1 节）。
模板来源属性只读	由属性模板下发到元素上的属性，其子属性由模板统一管理，元素上不可增删；只有在元素上直接创建的自定义属性才能添加、编辑、删除子属性。
模板元素禁配数据引用	由元素模板创建的元素，其自定义属性及子属性不能配置 TDengine 数据引用；如需引用 TSDB 数据，请在元素模板上添加相应属性。

3.2.10 表达式编辑器

表达式编辑器是 IDMP 中凡需配置表达式的地方都会用到的共用 UI 组件——包括公式和字符串构建器属性定义、分析输出属性，以及分析触发条件（预过滤和事件窗口表达式）。点击表达式输入框时，它会以弹窗形式打开。

3.2.10.1 表达式的使用场景

使用位置	用途
公式属性 — 数据引用设置	定义由同一元素其他属性推导而来的计算属性值
字符串构建器属性 — 数据引用设置	通过字符串函数组合属性值，构建字符串
面板 — 指标/维度表达式，过滤条件	组合属性值与子属性（含 KPI 子属性）构建展示序列和过滤条件
实时分析 — 输出属性，表达式列	每次分析触发时，计算并写入元素或事件属性的结果
实时分析 — 触发条件，预过滤	在触发条件评估前过滤数据行
实时分析 — 事件窗口触发，开始/结束条件	定义事件窗口的开启和关闭时机

3.2.10.2 表达式编辑器布局

弹窗分为三个面板：

属性（左侧） — 左侧面板标题为属性。默认列出当前元素上的属性，或当前元素模板上的属性模板。属性按以下类别直接平铺展示，同时提供替换参数展开节点：

分组	内容
指标	引用指标列的属性。若该属性配置了极限值，可展开查看并插入其包含的极限值。
标签	引用标签值的属性，包括外部数据源同步的标签。
公式	公式类型属性。
字符串构建	字符串构建器类型属性。
普通属性	不属于上述类型的其他属性。
替换参数	以可展开节点形式展示的系统级替换值，如 TIME（当前本地时间毫秒数）、当前元素名、属性名和模板名。

顶部的过滤输入框可按名称搜索。点击属性或参数，将其插入表达式的光标位置。

窗口伪列节点 — 在实时分析输出属性的表达式编辑器中，属性树会在替换参数之上额外显示窗口伪列分类（_twstart、_twend、_twduration），插入方式与属性相同，详见7.4.5 节。

子属性与 KPI 节点 — 挂有子属性的属性在树中可以展开：普通子属性（含一般子属性和数据引用子属性）作为叶子挂在父属性节点下，KPI 属性则作为纯分组节点展开显示其子属性。点击子属性节点，插入形如 ${attributes['父属性名']|childAttributes['子属性名']} 的引用。两点限制：

• KPI 属性不能被直接引用——KPI 属性自身无取值，必须展开选择其某个子属性。
• 未就绪的 KPI 子属性不可插入——KPI 构建未完成的子属性以及月/季派生子属性在树中置灰，悬浮显示原因。

表达式编辑器（中间） — 用于编写表达式的代码编辑器。顶部的运算符快捷栏提供常用运算符的一键插入：

+  -  *  /  =  <  >  >=  <=  !=  <>  &  |

函数面板（右侧） — 按类别浏览并插入函数。除内置函数分类外，还包含用户自定义函数分类。过滤输入框可按函数名搜索。点击函数名将其插入表达式的光标位置。

3.2.10.3 函数分类

分类	示例函数
数学函数	ABS, CEIL, FLOOR, ROUND, SQRT, LOG, POW, SIN, COS, ...
字符串函数	CONCAT, LENGTH, LOWER, UPPER, SUBSTR, TRIM, LTRIM, RTRIM, ...
转换函数	CAST, TO_ISO8601, TO_TIMESTAMP, ...
时间和日期函数	NOW, TODAY, TIMEZONE, TIMETRUNCATE, ...
聚合函数	AVG, COUNT, SUM, STDDEV, STDDEV_POP, PERCENTILE, SPREAD, ELAPSED, HISTOGRAM, ...
选择函数	MAX, MIN, FIRST, LAST, LAST_ROW, TOP, BOTTOM, UNIQUE, MODE, SAMPLE, ...
时序专用函数	MAVG, DERIVATIVE, DIFF, IRATE, CSUM, INTERP, TWA, STATECOUNT, STATEDURATION, ...
用户自定义函数	已在 TDengine TSDB 中注册的用户自定义函数。

3.2.10.4 评估表达式

在支持评估的场景（公式和字符串构建器属性定义）中，编辑器中间面板底部会显示评估按钮和评估结果区域。点击评估可对元素当前数据运行表达式，在保存前验证结果。

点击弹窗中的保存应用表达式，点击取消放弃更改。

3.2.11 属性模板

属性模板将一个标准属性——包括名称、数据类型、计量单位和数据引用绑定——定义为元素模板的一部分。从模板创建元素时，所有属性模板会自动实例化，替换字符串会解析为该元素的实际值。

3.2.11.1 创建属性模板

1. 在基础库中，打开要添加属性的元素模板。
2. 点击模板详情页顶部的属性模板选项卡。
3. 点击 + 打开属性模板创建表单。
4. 填写属性字段并配置数据引用绑定（见下文）。

3.2.11.2 属性模板字段

字段	说明
名称	属性名称，命名规则与属性相同（参见 3.2.3.1 节的命名规则说明）
描述	可选描述
配置	附加配置标志（如隐藏、常量）
类别	类别标签
值类型	数据类型：Float、Int、Varchar、Bool 等
默认值	可选默认值
默认计量单位	存储时使用的计量单位
显示计量单位	UI 中显示时使用的计量单位（可与存储单位不同）
显示精度	UI 中显示的小数位数
数据引用类型	属性与 TDengine TSDB 数据的绑定方式（见下文）
数据引用设置	解析后的绑定路径，如 TDengine/idmp_sample_utility/${KEYWORD1}/current
极限值配置	可选的高/低报警阈值
预测配置	可选的 TDgpt 预测配置

3.2.11.3 数据引用绑定

数据引用类型决定属性如何连接到 TDengine TSDB 中的时序数据：

数据引用类型	用途
无	无 TSDB 绑定——属性仅保存静态或计算值。
指标	将属性绑定到 TDengine 或外部数据源的时序指标列。
标签	引用 TDengine 标签值或外部数据源的元数据值。

选择指标或标签后，通过指定来源连接、数据库、表名（使用 ${KEYWORD1} 等替换字符串，使每个元素绑定到各自的表）和列名来配置绑定。以 TDengine 连接为例，数据引用设置的形式为：

TDengine/<数据库名>/${KEYWORD1}/<列名>

点击检查可验证绑定是否能正确解析。

属性模板同样支持选择 MySQL、PostgreSQL 和 InfluxDB 外部连接，取值方式与普通属性一致。模板中的表名、列名可使用替换字符串，实例化后解析为具体元素的引用。

在外部 TAG SQL 中引用静态属性或 TDengine TAG

例如，同一元素模板中有两个属性：设备编码 是无数据引用的字符串静态属性，所属区域 是从外部数据库读取的标签。先保存 设备编码 及其默认值（例如 PUMP-001），再为 所属区域 选择外部连接和 SQL 查询方式：

1. 在 SQL 编辑器中，输入 WHERE device_code =，再输入一个空格，将光标留在空格后。
2. 打开编辑器工具栏的插入属性列表，搜索并选择 设备编码。
3. 编辑器自动插入 ${attributes['设备编码']#value}。如果已选中一段 SQL，则替换选中的内容；可使用编辑器的撤销操作恢复。
4. 补全排序和行数限制，再点击检查。完整示例如下：

SELECT region
FROM device_history
WHERE device_code = ${attributes['设备编码']#value}
ORDER BY updated_at DESC, id DESC
LIMIT 1

该列表在元素和元素模板的外部 TAG SQL 编辑器中均可使用，每次展开都会读取已保存的属性。列表提供同一元素或模板中的顶层字符串、数字和布尔静态属性，以及原生 TDengine 连接的 TAG 属性，并排除正在编辑的属性、第三方查询 TAG 和公式。静态属性无值、名称重复或名称无法用于占位符时，选项会显示原因且不可选择。TDengine TAG 不要求填写默认值，其实际值在检查或执行查询时读取。如果列表为空，请先保存符合条件的属性，再重新展开列表。

这里的属性名必须与同一元素的顶层属性名称完全一致。SQL Server 使用 SELECT TOP (1) region ... ORDER BY updated_at DESC, id DESC，不使用 LIMIT 1。请根据源表选择时间列和唯一排序列，确保最新记录的选择确定且只返回一个值。

该写法沿用 IDMP 的属性路径语法：${...} 标记需要解析的引用，attributes['设备编码'] 按名称定位属性，#value 表示取属性值。它不是数据库原生 SQL 语法；执行前 IDMP 会将引用转换为值参数。当前外部 TAG SQL 必须保留 #value，且不支持通用路径表达式中的其他字段或跨元素路径。

• 不要给占位符添加引号，即使引用字符串属性也一样。系统按属性类型绑定参数，属性值中的引号不会被当作 SQL 语法。数字和布尔静态属性使用相同写法。
• 在属性模板中检查时，使用已保存的静态属性模板默认值；在元素中检查、首次取值和后续自动同步时，使用该元素当前的静态属性值，包括元素对模板默认值的覆盖。静态属性修改保存后，下一轮自动同步会重新读取参数；关闭自动同步则不会定时刷新。
• 设备编码 也可以是 TDengine TAG，SQL 写法不变。对于已发布的 TAG，查询前读取元素实际表上的当前 TAG 值，支持 Tag-Ref 和字面量 TAG，不使用 JSON 中的旧默认值代替实际值。Tag-Ref 跟随源 TAG；字面量 TAG 使用自身保存的值，不会因为原始源表变化而自动跟随。
• 模板检查没有元素实际表，因此从引用的 TDengine 源表读取 TAG；首次建表或依赖 TAG 尚未发布时也从源表取值。本地自动生成、尚未发布的静态 TAG 使用配置值。源表名称中的替换字符串须先能解析为具体名称，否则检查失败。下一轮自动同步会重新读取 TDengine TAG，再执行第三方 SQL。
• SQL 模板本身保留占位符。例如，两个元素的 设备编码 分别为 PUMP-001 和 PUMP-002，它们使用同一条 SQL 配置，执行时各自过滤对应设备的数据。
• 当前仅支持同一元素的顶层字符串、数字和布尔静态属性及原生 TDengine TAG，采用一层取值，不执行被引用属性的 SQL 或公式。不支持指标、第三方查询 TAG、公式、其他元素、子属性、特征、列表或对象，也不支持把引用用于表名、列名、SELECT 列表、ORDER BY 或 LIMIT。
• 引用的属性不存在、没有值、类型不受支持或 TDengine 读取失败时，检查或首次取值报错；定时同步不写入新值，保留上次成功值。SQL NULL 不会被转换成字符串 null，也不会回退到旧默认值。属性重命名后须同步修改 SQL 中的引用名称。第三方 SQL TAG 的自引用和相互引用会被拒绝，不会进入递归查询。

该占位符属于 SQL 查询方式的值参数，与“表 / 列”方式中的表名替换字符串用途不同。修改静态属性或 SQL 后，请重新点击检查。

3.2.11.4 子属性模板

属性模板同样支持子属性模板，在属性模板的创建/编辑表单中的子属性折叠面板内管理，操作方式与元素属性相同（参见 3.2.9.1 节）。子属性模板支持两类：

• 一般子属性模板——不配置数据引用。元素实例化时，一般子属性自动物化为元素虚拟表上的标签列。
• 数据引用子属性模板——可配置公式等数据引用，绑定路径中可使用 ${KEYWORD1} 等替换字符串。

模板上的子属性增删改会同步到使用该模板的所有元素：新增的子属性自动下发并物化到各元素的虚拟表，删除的子属性从各元素上移除。在元素侧，模板下发的子属性由模板统一管理（只读），用户只能在元素的自定义属性上自行添加子属性。

3.2.12 KPI 属性

KPI 属性是一类特殊的聚合属性，用于将源属性（如指标或公式属性）按聚合函数和统计周期持续计算为关键绩效指标（KPI）。与普通属性保存单一测点不同，一个 KPI 属性可包含多个子属性，每个子属性对应「一个聚合函数 × 一个统计周期」的组合（如「平均值 / 小时」「求和 / 天」）。系统会为 KPI 属性自动创建流计算与对应的输出表，实时维护各子属性的值。

3.2.12.1 范围

创建 KPI 属性时，首先选择聚合的数据来源范围：

范围	说明
子元素	从本元素的所有子元素的源属性聚合计算（本元素无子元素时不可用）
仅本元素	仅从本元素自身的源属性计算

3.2.12.2 源属性

• 当范围为子元素时，需先选择子元素的属性模板，再从该模板下选择源属性。
• 当范围为仅本元素时，直接从本元素的属性中选择源属性。

源属性的数据引用类型须为指标或公式；文件、视频、元素引用、KPI 等值类型不可作为 KPI 源。

3.2.12.3 KPI 定义

在「KPI 定义」表中添加一条或多条子属性定义，每条包含：

字段	说明
名称	子属性的逻辑名称（如 avg_power）
聚合函数	聚合方式：AVG、MAX、MIN、SUM、COUNT、LAST、FIRST、HYPERLOGLOG、SPREAD、STDDEV、STDDEV_POP、VAR_POP 等
周期	统计周期，可多选：小时、天、周、月、季。每勾选一个周期即生成一个对应子属性（如 avg_power 的小时与天两个子属性）

3.2.12.4 计算层级

聚合在资产层级上的展开方式：

层级	说明
从本级开始	从当前元素层级向下聚合
从顶级开始	从资产树顶层向下聚合
仅本级	仅本级，不向下递归聚合

3.2.12.5 其他选项

选项	说明
历史回填起始	可选。指定起始时间后，系统回填该时间至今的历史数据；留空表示不回填
显示值	可选。指定在面板等位置默认展示哪一个子属性的值

3.2.12.6 构建状态

保存后系统会创建流计算与输出表，KPI 属性进入构建流程，状态包括：

状态	说明
构建中	正在创建流与输出表
已生效	构建完成，正常计算
构建失败	构建出错，可重试重建

KPI 属性是 KPI 报表面板的数据来源。在 KPI 报表中选择 KPI 子属性作为列，即可按统计周期展示并对比（环比 / 同比）各资产的 KPI 值。

KPI 属性自身不能被表达式直接引用，但其子属性可以在公式属性、字符串构建属性、面板以及实时分析的表达式中引用，语法为 ${attributes['父属性名']|childAttributes['子属性名']}（在表达式编辑器的属性树中点击子属性节点即可插入）。公式与面板场景要求 KPI 已构建完成；引用 KPI 子属性与实时属性做运算时，注意时间戳对齐问题（参见 3.2.2.3 节的 FILL_FORWARD 说明）。