企业官网建设流程全解析

TDengine PI 数据接入模型配置文件（CSV）完整参考：多列与单列模型的映射规则详解

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

本文系统讲解 TDengine 从 PI 系统（OSIsoft PI / Aveva PI System）同步数据所使用的模型配置文件——一个 CSV 格式的纯文本文件，它定义了 PI Point / AF 元素到 TDengine 超级表、子表、Metric 列与 TAG 列的完整映射规则。读完本文，你将能够独立编写、编辑和排错 PI 任务的模型配置：理解多列模型与单列模型的两种文件格式，掌握占位符与内联表达式语法，并按 UOM 分组、过滤点位等最佳实践定制自己的配置。

模型配置文件是什么

模型配置文件定义了从 PI 系统到 TDengine 的数据映射规则，具体包括四类信息：

• PI 数据源（PI Point 或 AF 元素模板）与 TDengine超级表的对应关系
• PI 属性与 TDengine列（Metric 列、TAG 列）的映射
• 数据过滤条件
• 数据转换表达式

文件格式为 CSV 文本，由若干行“逗号分隔”的规则组成，因此可以直接用文本编辑器打开、用 Excel 查看、用 Git 做版本管理。文件内容在 taosExplorer 创建 PI 任务时上传，taosX 在任务启动时解析该文件并据此自动建表（超级表/子表）、拉取数据。

配置的生成与修改流程

在 taosExplorer 中创建 PI 任务（类型选PI实时任务或PI backfill回填任务）时，数据模型配置区域提供下载默认配置按钮：点击后 taosX 会连接 PI 系统，扫描符合条件的 PI Point / AF 模板，自动生成一份默认的模型配置文件并下载到本地。标准工作流是：

1. （可选）先填写Dataset Filter，圈定要同步的点位/元素/模板范围；
2. 点击下载默认配置，获得一份可直接运行的 CSV；
3. 本地编辑（增删超级表、调整列类型、加转换表达式、删点位行）；
4. 重新上传，覆盖默认配置后提交任务。

需要注意任务类型与数据模型之间的约束（来自 PI 数据接入总览）：

多列模型依赖 AF 资产框架（元素、模板、属性），因此只在AF Server 模式下可用；多列模型的实时任务还额外提供“同步新增/删除元素、同步静态属性变化、同步修改/删除历史数据”等高级开关，这些能力都建立在“一个 AF 元素 = 一张子表”的映射之上。

多列模型配置文件

多列模型将一个 PI AF 元素映射为 TDengine 的一张子表，属于“以设备/资产为中心”的数据采集模型：一个元素模板（Template）下的所有元素共享同一个超级表结构，每个元素对应一张子表，元素的多个 PI Point 属性变成一行中的多个列。

文件结构

多列模型配置文件由一个或多个超级表定义块组成，块与块之间用空行分隔。每个超级表定义块包含：

列定义说明

列定义行的第二列是关键字，决定该列的角色：

这与 TDengine 超级表模型一一对应：KEY即时间戳主键列，COLUMN构成每行记录的度量字段，TAG构成子表级别的标签。由于同一模板下所有元素的属性集合一致，才能保证同一超级表内所有子表列结构完全一致。

完整示例

以下配置文件定义了两个超级表：metertemplate（来自 MeterTemplate 模板）和farm（来自 Farm 模板）：

SuperTable,metertemplate SubTable,${element_name}_${element_id} Template,MeterTemplate Filter, ts,KEY,TIMESTAMP,$ts voltage,COLUMN,DOUBLE,$voltage voltage_status,COLUMN,INT,$voltage_status current,COLUMN,DOUBLE,$current current_status,COLUMN,INT,$current_status element_id,TAG,VARCHAR(100),$element_id element_name,TAG,VARCHAR(100),$element_name path,TAG,VARCHAR(100),$path categories,TAG,VARCHAR(100),$categories SuperTable,farm SubTable,${element_name}_${element_id} Template,Farm Filter, ts,KEY,TIMESTAMP,$ts wind_speed,COLUMN,FLOAT,$wind_speed wind_speed_status,COLUMN,INT,$wind_speed_status power_production,COLUMN,FLOAT,$power_production power_production_status,COLUMN,INT,$power_production_status lost_power,COLUMN,FLOAT,$lost_power lost_power_status,COLUMN,INT,$lost_power_status farm_lifetime_production__weekly_,COLUMN,FLOAT,$farm_lifetime_production__weekly_ farm_lifetime_production__weekly__status,COLUMN,INT,$farm_lifetime_production__weekly__status farm_lifetime_production__hourly_,COLUMN,FLOAT,$farm_lifetime_production__hourly_ farm_lifetime_production__hourly__status,COLUMN,INT,$farm_lifetime_production__hourly__status element_id,TAG,VARCHAR(100),$element_id element_name,TAG,VARCHAR(100),$element_name path,TAG,VARCHAR(100),$path categories,TAG,VARCHAR(100),$categories

逐行解读

以metertemplate超级表为例：

• SuperTable,metertemplate：定义超级表名为metertemplate
• SubTable,${element_name}_${element_id}：子表名由元素名和元素 ID 拼接，如Meter001_12345。带上元素 ID 可以防止两个同名元素产生子表名冲突
• Template,MeterTemplate：数据来自 PI AF 中名为MeterTemplate的元素模板
• Filter,：留空表示不做过滤，同步该模板下的所有元素
• ts,KEY,TIMESTAMP,$ts：时间戳列，取 PI 数据的时间戳
• voltage,COLUMN,DOUBLE,$voltage：数据列，取元素的voltage属性值
• voltage_status,COLUMN,INT,$voltage_status：数据列，取voltage的质量状态码（PI Point 的 condition/status）
• element_id,TAG,VARCHAR(100),$element_id：标签列，取元素的唯一 ID
• path,TAG,VARCHAR(100),$path：标签列，取元素在 AF 层级中的路径

两个细节值得注意：

1. status 列与 value 列成对出现：PI 的每个数据点都带有质量状态（good/bad/uncertain 等），将其落为INT列入库后，后续可以用 TAG/列查询数据可信区间，这是工业数据落库的常见做法。
2. 列名做了 TDengine 合法化处理：farm_lifetime_production__weekly_这类列名用双下划线和尾下划线替代了 PI 属性名中的空格/特殊字符。从示例可以看出，列名必须满足 TDengine 标识符规则，PI 属性名中的非法字符要在映射规则里显式处理。

默认映射规则

对于使用 AF Server 的多列模型任务，taosX 生成默认配置时遵循的规则是：

• PI Point 属性（可产生时序值的属性）默认映射为 TDengineCOLUMN（Metric 列）
• 其他属性（静态属性）默认映射为 TDengineTAG列

这意味着默认配置通常已经可直接使用：你只需关注类型是否合适（DOUBLE/FLOAT/INT）、TAG 长度是否足够（VARCHAR 长度），以及是否需要额外的过滤和转换。

单列模型配置文件

单列模型将一个 PI Point 映射为 TDengine 的一张子表，属于“以点位为中心”的数据采集模型。每个点位子表只有一列（或少数几列）时序值，点位的大量元数据（单位、描述、来源等）沉淀为 TAG。

文件结构

单列模型配置文件分为两个部分：

1. 超级表定义：定义若干个超级表的列结构（与多列模型的行格式一致，但没有Template行）。默认生成的配置会按UOM（工程单位）+ 数据类型将点位自动分组到不同的超级表——例如所有单位为 Volt 且数据精度为 Float32 的点位归入volt_float32。

2. 点位映射：格式为<Point名称>,POINT,<超级表名>，逐行声明每个 PI Point 属于哪个超级表，从而决定它在哪张超级表下创建子表。

完整示例

SuperTable,volt_float32 SubTable,${point_name} Filter, ts,KEY,TIMESTAMP,$ts value,COLUMN,FLOAT,$value status,COLUMN,INT,$status path,TAG,VARCHAR(200),$path point_name,TAG,VARCHAR(100),$point_name ptclassname,TAG,VARCHAR(100),$ptclassname sourcetag,TAG,VARCHAR(100),$sourcetag tag,TAG,VARCHAR(100),$tag descriptor,TAG,VARCHAR(100),$descriptor exdesc,TAG,VARCHAR(100),$exdesc engunits,TAG,VARCHAR(100),$engunits pointsource,TAG,VARCHAR(100),$pointsource step,TAG,VARCHAR(100),$step future,TAG,VARCHAR(100),$future element_paths,TAG,VARCHAR(512),`$element_paths.replace("\\", ".")` SuperTable,milliampere_float32 SubTable,${point_name} Filter, ts,KEY,TIMESTAMP,$ts value,COLUMN,FLOAT,$value status,COLUMN,INT,$status path,TAG,VARCHAR(200),$path point_name,TAG,VARCHAR(100),$point_name ptclassname,TAG,VARCHAR(100),$ptclassname sourcetag,TAG,VARCHAR(100),$sourcetag tag,TAG,VARCHAR(100),$tag descriptor,TAG,VARCHAR(100),$descriptor exdesc,TAG,VARCHAR(100),$exdesc engunits,TAG,VARCHAR(100),$engunits pointsource,TAG,VARCHAR(100),$pointsource step,TAG,VARCHAR(100),$step future,TAG,VARCHAR(100),$future element_paths,TAG,VARCHAR(512),`$element_paths.replace("\\", ".")` Meter_1000004_Voltage,POINT,volt_float32 Meter_1000004_Current,POINT,milliampere_float32 Meter_1000001_Voltage,POINT,volt_float32 Meter_1000001_Current,POINT,milliampere_float32 Meter_1000474_Voltage,POINT,volt_float32 Meter_1000474_Current,POINT,milliampere_float32

逐行解读

超级表定义部分：

• SuperTable,volt_float32：超级表名为volt_float32（电压类 float32 点位）
• SubTable,${point_name}：子表名直接使用点位名，例如Meter_1000004_Voltage
• value,COLUMN,FLOAT,$value：数据列，存储点位的值
• status,COLUMN,INT,$status：数据列，存储质量状态码
• point_name,TAG,VARCHAR(100),$point_name：标签列，存储点位名称
• engunits,TAG,VARCHAR(100),$engunits：标签列，存储工程单位（UOM），这正是默认分组依据的字段
• element_paths,TAG,VARCHAR(512),`$element_paths.replace("\\", ".")`：标签列，使用内联表达式将 PI 元素路径中的分隔符从\替换为.，使路径风格与 TDengine 侧的命名习惯一致

点位映射部分：

• Meter_1000004_Voltage,POINT,volt_float32：点位Meter_1000004_Voltage归属于超级表volt_float32
• Meter_1000004_Current,POINT,milliampere_float32：点位Meter_1000004_Current归属于超级表milliampere_float32

从点位命名（Meter_1000004_Voltage/_Current）可以看出该场景来自电力计量：同一块电表下电压、电流点位分属不同 UOM，因此被默认配置分入不同超级表。若希望进一步按资产归组，可直接修改POINT行引用的超级表名。

映射规则与表达式

常用占位符

以下占位符可在列定义的映射规则中使用：

$<属性名>是最灵活的一类：多列模型中它引用 AF 元素的属性（PI Point 属性映射为 COLUMN，静态属性映射为 TAG，见上文“默认映射规则”）；单列模型中$ptclassname、$sourcetag、$engunits等实际上都是 PI Point 的属性名，按需引用即可。

内联表达式

对于需要数据转换的场景，映射规则列可以用反引号包裹内联表达式：

element_paths,TAG,VARCHAR(512),`$element_paths.replace("\\", ".")`

表达式内部支持对字符串字段调用处理方法（如replace），占位符先取源值、再执行表达式、最后写入目标列。这与 TDengine 零代码写入平台内置 ETL 的“转换/映射”能力一脉相承，更完整的映射规则与表达式语法（解析、过滤、映射、格式化处理函数、数学表达式等）请参阅 零代码数据写入 的“数据提取、过滤和转换”部分。

子表名占位符

SubTable行的模板支持以下占位符：

占位符可以组合使用，如${element_name}_${element_id}。选择建议：

• 单列模型一般直接用${point_name}，点位名在 PI Data Archive 内天然唯一；
• 多列模型推荐${element_name}_${element_id}：元素名在同一模板下可能重复，拼上 ID 可避免子表名冲突；
• 子表名最终必须满足 TDengine 子表名规则（长度与字符集限制），元素名过长时建议仅用${element_id}。

常见模式与最佳实践

按 UOM 分超级表

默认生成的单列模型配置会按UOM（工程单位）+ 数据类型自动分组：所有单位为 "Volt" 且数据类型为 Float32 的点位归入同一个超级表volt_float32，毫安类点位归入milliampere_float32。

这是推荐的默认做法，因为它保证了同一超级表中所有子表的列结构完全一致——这正是 TDengine 超级表模型对子表的要求，也便于按单位维度做跨设备的聚合查询（如SELECT AVG(value) FROM db.volt_float32 WHERE ...）。

过滤特定点位或模板

两种操作路径：

1. 下载前过滤：在 taosExplorer 中先填写 Dataset Filter，再点击下载默认配置，生成的配置就只包含匹配范围。Filter 的可用单位取决于连接方式与数据模型（point/element/template），支持*、?通配符，完整语法见 Dataset Filter 配置。
2. 下载后手动编辑 CSV：
   • 多列模型：修改超级表定义块中的Filter行（该行的值就是生成时使用的 Dataset Filter）；
   • 单列模型：在点位映射部分删除不需要的POINT行。

注意一个容易踩的坑：AF Server 模式下的单列模型，Dataset Filter 只支持element/template而不支持point——因为 AF 单列需要经由 Element → Attribute 上下文获取 UOM、元素归属等元数据，直接用点位名过滤会丢失这些信息。

自定义超级表名

如果默认按 UOM 分组的命名不满足需求（例如希望按产线、区域或资产类别组织超级表），可以直接修改SuperTable行的值，并同步调整点位映射部分引用的超级表名；多列模型则修改Template行关联的模板名并调整列定义即可。修改后上传覆盖默认配置，任务重启生效。

与任务配置的关系：配置文件中没有的东西

模型配置文件只负责“映射”，其他运行时参数在 taosExplorer 的任务配置中完成，理解两者的边界有助于排错：

另外，PI 连接器依赖 PI AF SDK，仅支持 Windows 环境，网络侧需放通 5450（Data Archive）与 5457（AF Server）端口；若 taosX 部署在非 Windows 主机，需通过部署在 Windows 上的 taosX-Agent 代理接入。部署与认证细节分别见 部署架构 与 连接配置与认证。

小结

• 模型配置文件是 PI 任务的核心资产：多列模型按“模板块”定义（SuperTable/SubTable/Template/Filter+ 列定义），单列模型则是“超级表定义 +POINT点位映射”两部分；
• 列定义用KEY/COLUMN/TAG三类关键字对齐 TDengine 超级表结构，映射规则列支持$占位符与反引号包裹的内联表达式；
• 工作流上优先使用“Dataset Filter → 下载默认配置 → 本地编辑 → 上传覆盖”，按 UOM + 数据类型分组、element_name_element_id组子表名、value/status 成对入库是默认且推荐的实践。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine