12.3 从 TDengine TSDB 构建数据模型

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

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

选项卡	最适合场景
简单导入	具有层级位置标签的结构良好 TSDB 数据——最快捷的完整模型构建路径
超级表映射为元素	没有位置标签的数据，或需要将多个超级表映射到一个元素模板的场景
从文件导入	通过 Markdown 文件批量配置，支持多文件批量上传与批量展开，适合大规模建模
从 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 从文件导入

从文件导入是超级表映射为元素的批量替代方案。当需要配置大量超级表与元素时，使用 Markdown 文件按「一个元素一个块」描述模型，比通过界面逐一操作更为高效；团队成员还可以各自准备文件，一次上传多个文件批量导入。

工作流程：

点击工具栏中的生成基础 MD按钮，基于 TSDB Schema 生成基础配置文件。选择要包含的数据库和超级表。可选勾选包含子表，逐子表生成固定块骨架——适用于每个子表需要特定元素名称或路径的情况。生成的文件为待编辑骨架，待补充 根路径必须先替换为真实业务路径后再上传。
编辑生成的文件，补充元素路径、描述、属性映射及其他配置。导入弹窗中可按当前界面语言下载空白参考模板。
点击工具栏中的导入按钮，选择一个或多个填写好的 .md 文件一次提交。导入任务立即启动；一次多文件提交会创建一个批量任务，任务内按上传顺序串行处理文件。

任务历史记录表显示：创建时间、状态、文件名（批量任务的全部文件名逐个可下载）、订阅状态和原因（失败时显示，批量任务含逐文件失败摘要）。导入期间进度对话框逐文件展示处理状态（待处理、处理中、完成、失败及原因）；单个文件失败不影响其他文件。

自动同步： 包含批量展开块的导入任务完成后，IDMP 会监听 TSDB 的元数据变更，匹配子表过滤条件的新增子表将自动同步为新元素。订阅可在任务列表中单独启动或停止。

MD 配置文件说明：

文件由若干元素块组成；每个元素块以 element:start 注释标记开始、以 element:end 注释标记结束（语言无关保留字，不要翻译或修改）。块外内容会被忽略，可用于书写说明文字。
## 元素：<路径> 是元素路径与名称的唯一来源，以英文句点 . 分层，末段为元素名；中间节点不存在时由系统自动创建。
每个表格的前两行（表头行与分隔行）按位置跳过；数据行必须恰好两列；同一表格内字段键不得重复。值中的竖线用 \| 转义、字面反斜杠用 \\ 转义。
空单元格、仅空白、或字面量 （空）/(空) 均视为未填写。
字段键支持中文、英文、韩文、西班牙文四种语言并集匹配，导入弹窗内可下载对应语言的空白参考模板。
元素模板可留空（固定块）：留空时不创建元素模板，元素创建为无模板的自由元素。批量块留空时按 <数据库名>_<超级表名> 自动创建。
配置文件必须使用 UTF-8 编码（容忍 BOM，换行 LF 或 CRLF 均可）。

两种块模式：

固定块：元素路径不含 ${...} 表达式且未填子表过滤。每个属性必须指定具体子表；不同属性可引用不同的数据库、超级表、子表。
批量块：元素路径含 ${...} 表达式或填了子表过滤。按过滤条件把超级表的子表批量展开为元素；表达式支持 ${tbname}（子表名称）和 ${标签名}（标签值），可用位置为元素路径、描述、分类。

基本信息与元素描述字段：

字段	说明
元素模板	目标元素模板。固定块留空表示无模板自由元素；批量块留空时按 `<数据库名>_<超级表名>` 自动创建；填写且不存在时按块内属性自动创建；已存在时只补缺失属性
子表过滤	SQL WHERE 风格的过滤表达式（批量块的展开条件），如 `line_tag is not null`
位置 · 海拔（米）	数字，仅固定块可用（可选）
位置 · 经度	数字，-180 到 180，仅固定块可用（可选）
位置 · 纬度	数字，-90 到 90，仅固定块可用（可选）
描述	元素描述，批量块中支持 `${...}` 表达式（可选）
分类	英文逗号分隔的分类名，批量块中支持表达式（可选）

属性字段：

每个属性以 #### 属性 N 小节标题开始（N 仅为可读性编号），小节内的表格字段如下：

字段	说明
属性名称	属性的名称（即属性模板名），为每个属性表格的第一行。以 `Quality:` 开头表示质量列配置段，详见下方"配置质量列"。留空时按超级表列名缺省
数据库名称	源 TDengine 数据库（必填）
超级表	测点数据所在超级表（必填）
超级表列名	数据所在列名；质量列配置段中指质量列名（必填）
引用类型	`TDengineMetric`（指标）或 `TDengineTag`（标签），留空时按超级表 Schema 推断（可选）
子表	固定块必填具体子表名；批量块必须留空（引用当前展开的子表）
属性描述	属性描述（可选）
属性分类	英文逗号分隔（可选）
默认计量单位名称	仅可引用系统中已有的计量单位（按名称或缩写匹配）；引用不存在的单位会导致整个文件在创建前失败，并一次性列出全部缺失单位（可选）
显示计量单位名称	用于显示的计量单位，规则同上（可选）
显示位数	数值显示的小数位数，非负整数（可选）

配置质量列：

如需为某个指标配置数据质量列，在同一元素块中额外添加一个属性段：

属性名称填 Quality:<指标属性名称>，例如 Quality:旋转速度（前缀大小写敏感，quality: 或 QUALITY: 不生效）；
超级表列名填源超级表中实际的质量列列名，例如 val_q。

规则说明：

质量列配置段本身不会创建属性模板，仅把质量列名记录到对应指标的属性模板上（模板已存在则直接更新）。
导入完成后，虚拟超级表会自动增加对应的质量列，面板与历史查询即可读取质量值。

备注

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

12.3.4 从 OPC 导入

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

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

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

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

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