12.3 从 TDengine TSDB 构建数据模型

对于已在使用 TDengine TSDB 的用户，IDMP 可以直接从 TSDB 的 Schema 自动构建资产数据模型——包括元素、元素模板和属性。这省去了手动创建元素和属性的工作量。

IDMP 提供四种方式，均可从 管理后台 → 连接 → [连接名称] 下的 TDengine 连接详情页访问：

选项卡	最适合场景
简单导入	具有层级位置标签的结构良好 TSDB 数据——最快捷的完整模型构建路径
超级表映射为元素	没有位置标签的数据，或需要将多个超级表映射到一个元素模板的场景
从 CSV 导入	通过 CSV 文件批量配置，尤其适合单列数据模型和大量超级表
从 OPC 导入	已在 TSDB 中存储的 OPC 结构数据

12.3.1 简单导入

当 TSDB 超级表已有编码了资产层级的标签时，简单导入效果最佳——例如，location 标签的值是以点分隔的路径，如 Plant.Line1.Machine3。IDMP 将每个超级表映射为一个元素模板，将每个子表映射为一个元素实例。

使用方法：

在页面顶部选择数据库和超级表。勾选忽略可跳过某个超级表。
在标签区域，配置每个标签：
- 勾选路径，将标签值用作元素在资产树中的位置。设置路径层级（0 = 叶子节点）以控制层级深度。可选择设置父元素，将导入内容根植于某个已有元素之下。
- 勾选路径后，会出现元素路径表达式编辑器，用于自定义元素在资产树中的路径结构。表达式使用点号分隔层级，支持固定文本和 ${标签名} 替换变量。默认值为 {重命名}.${标签名}。例如：
  - 位置.${location} — 创建固定层级"位置"，其下按 location 标签值展开
  - ${province}.${city}.${district} — 使用多个标签联合构建多级路径，系统会自动查询实际存在的标签值组合（避免笛卡尔积）
  - 标签值本身包含点号（如 北京.朝阳）时，会自动拆分为多级层级
- 不勾选路径，则将该标签作为静态属性（元素属性）导入。
- 使用重命名字段为属性设置不同于 TSDB 列名的显示名称。修改重命名时，路径表达式中的默认前缀会自动同步更新。
- 可选择分配属性分类。
在指标区域，勾选超级表映射为元素，为要导入为动态属性的每个指标列进行配置。根据需要使用重命名和属性分类。
可选择设置元素分类和子表过滤条件（SQL WHERE 风格的表达式，仅包含匹配的子表）。
点击下一个超级表继续配置下一个超级表，或点击完成立即使用剩余超级表的默认值完成配置。

页面底部的摘要显示当前超级表中已选标签和指标的数量，以及已选与已忽略超级表的总数。

自动同步： 导入任务运行后，IDMP 会监听 TSDB 的元数据变更。已配置超级表中新增的子表将自动同步为新元素，无需人工干预。

重新设置： 如果数据库中新增了超级表，点击 Rebuild 重新打开配置，原有设置将被预加载。添加新超级表后保存即可。

数据情境化： 导入后，为每个元素添加计量单位、描述、分类和极限阈值，赋予数据业务语义，使其具备 AI-Ready 的能力。

12.3.2 超级表映射为元素

当 TSDB 数据缺少层级标签、使用单列模型（每种测量量对应一张超级表），或需要将多张超级表的列映射到单个元素模板时，使用此方式。

IDMP 内部会自动创建虚拟超级表和虚拟表，将多张超级表的数据合并到一个统一的元素中——此过程对用户透明。

超级表映射为元素选项卡显示已配置资产模型的列表，包含以下列：数据库、超级表、元素模板名称、状态、创建时间和更新时间。

点击 + 新建资产模型配置新的映射。表单包含以下字段：

字段	说明
数据库	源 TDengine 数据库
超级表	源超级表
元素模板（必填）	要映射到的元素模板。开始前必须在基础库中创建好。
元素名称（必填）	定义元素名称的表达式。点击 + 可插入替换字符串（如标签值）。点击预览图标验证结果。
元素路径（必填）	定义元素在资产树中位置的表达式。用点分隔层级，如 `${location}.${rack}`。点击预览图标验证。
元素分类	已创建元素的可选分类标签
标签	将每个超级表标签映射到元素模板上的属性模板，或选择无丢弃
指标	将每个超级表指标列映射到属性模板，或选择无丢弃
子表过滤条件	可选的过滤表达式，仅包含匹配的子表

点击完成创建资产模型。每个资产模型对应一个超级表到模板的映射。对于完整的单列数据模型，需要为每个超级表（或每组指标子集）创建一个资产模型。

自动同步： 映射超级表中新增的子表将自动同步为新元素。

备注

数据库中在设置后新增的超级表，需要手动为其添加新的资产模型。新增超级表不会被自动检测。

12.3.3 从 CSV 导入

CSV 导入是超级表映射为元素的批量替代方案。当需要配置大量超级表（尤其是单列模型）时，使用电子表格定义所有映射比通过界面逐一操作更为高效。

工作流程：

点击工具栏中的导出图标（下载）导出基于 TSDB Schema 的 CSV 配置模板。选择要包含的数据库和超级表。可选勾选导出子表名称，将各子表名称一并导出——适用于每个子表需要特定元素名称或路径的情况。
编辑 CSV 文件，填写元素名称表达式、元素路径表达式、属性模板映射及其他配置。
点击工具栏中的导入图标（上传）上传填写好的 CSV 文件。导入任务立即启动。

任务历史记录表显示：创建时间、状态、文件名和原因（失败时显示）。

自动同步： 未指定特定子表名称过滤条件的任务，将自动同步数据库中新增的子表。

CSV 配置文件说明：

注释行以 # 开头，且注释行不会被处理，不可删除。
第一个非注释行是标题行。
数据按块划分；每块以设置数据库名称和超级表名称的行开始。
如未指定元素模板，将自动使用超级表名创建一个。
元素名称表达式支持替换字符串，如 ${tbname}（子表名称）或标签值 ${tag_name}。
元素路径表达式支持相同的替换字符串。值中的点会自动创建层级。
引用类型必须为 TDengineMetric 或 TDengineTag。
属性模板名称用于引用基础库中已存在的同名属性模板；留空或名称不存在时，按超级表列名自动创建属性模板（并自动打上"自动导入"分类）。
模板表头随界面语言区分（中文、英文表头不同），导入文件的表头必须与所用语言的导出模板保持一致，不可混用。
配置文件必须使用 UTF-8 编码（不支持带 BOM 的 UTF-8）。在 Windows 上使用 Excel 编辑时，上传前请转换编码格式。

CSV 配置列说明：

列	说明
数据库名称	源 TDengine 数据库，每个数据块的起始行必填
超级表名称	源超级表，每个数据块的起始行必填
元素模板名称	目标元素模板。留空时按超级表名自动创建
元素模板分类	元素模板的分类表达式（可选）
子表名称	指定子表后逐子表配置（导出时勾选导出子表名称生成），可为每个子表定制元素名称与路径；包含子表名称配置的任务不会自动同步新增子表
子表过滤规则	SQL WHERE 风格的过滤表达式，仅导入匹配的子表
元素名称表达式	元素名称，支持 `${tbname}`（子表名称）和 `${标签名}` 替换字符串
元素描述表达式	元素描述，支持相同的替换字符串
元素路径表达式	元素在资产树中的位置，点号分隔层级，支持相同的替换字符串
超级表列名	本行映射的标签列或指标列名
属性模板名称	映射的属性模板名。以 `Quality:` 开头表示质量列配置行，详见下方"配置质量列"
引用类型	`TDengineMetric`（指标）或 `TDengineTag`（标签）
属性模板分类	属性模板的分类表达式（可选）
属性模板描述	属性模板的描述（可选）
属性模板是否隐藏	`true` / `false`（可选）
属性模板是否排除	`true` / `false`（可选）
属性模板默认计量单位	计量单位名称或缩写（可选）
属性模板显示计量单位	用于显示的计量单位（可选）
属性模板默认值	属性的默认值（可选）
属性模板显示数字位数	数值显示的小数位数（可选）

配置质量列：

如需为某个指标配置数据质量列，在该指标所属的数据块中额外添加一行：

引用类型填 TDengineMetric；
属性模板名称填 Quality:<指标属性模板名>，例如 Quality:voltage（前缀大小写敏感，quality: 或 QUALITY: 不生效）；
超级表列名填源超级表中实际的质量列列名，例如 quality。

规则说明：

质量列配置行本身不会创建属性模板，仅把质量列名记录到对应指标的属性模板上（模板已存在则直接更新）。
建议将质量列配置行放在对应指标行之后，确保属性模板已创建、配置立即生效。
导入完成后，虚拟超级表会自动增加 <指标列>_q 质量列，面板与历史查询即可读取质量值。
导出的 CSV 模板不会自动包含质量列配置行，需要手工添加。

备注

CSV 导入任务创建后，如果 TSDB 中新增了超级表，需要为这些超级表创建新的导入任务。已有任务不会自动检测新增超级表。

12.3.4 从 OPC 导入

当 OPC 结构数据已存储在 TDengine TSDB 中时，使用此方式从中构建资产模型。

从 OPC 导入选项卡显示每个数据库的以下配置：

字段	说明
数据库	源 TDengine 数据库
父元素	可选的已有元素，将导入的元素根植于其下
忽略	勾选以跳过此数据库

对于数据库中的每个超级表，配置以下内容：

列	说明
复选框	包含或排除此超级表
超级表名称	要导入的超级表
路径	值表示 OPC 节点路径的标签列
数据列	包含数据值的指标列
质量列	可选的包含数据质量值的标签或列
路径层级	路径中的开始生效的层级，例如 Objects.A.B，如果生效层级为 1，那么路径会被直接处理为 A.B