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 模板自动生成一份默认的模型配置文件并下载到本地。标准工作流是可选先填写Dataset Filter圈定要同步的点位/元素/模板范围点击下载默认配置获得一份可直接运行的 CSV本地编辑增删超级表、调整列类型、加转换表达式、删点位行重新上传覆盖默认配置后提交任务。需要注意任务类型与数据模型之间的约束来自 PI 数据接入总览数据源类型支持的数据模型说明PI Data Archive Only仅单列模型直接连接 PI Data Archive ServerPI Data Archive AF Server单列模型、多列模型通过 PI AF SDK 连接支持完整资产框架多列模型依赖 AF 资产框架元素、模板、属性因此只在AF Server 模式下可用多列模型的实时任务还额外提供“同步新增/删除元素、同步静态属性变化、同步修改/删除历史数据”等高级开关这些能力都建立在“一个 AF 元素 一张子表”的映射之上。多列模型配置文件多列模型将一个 PI AF 元素映射为 TDengine 的一张子表属于“以设备/资产为中心”的数据采集模型一个元素模板Template下的所有元素共享同一个超级表结构每个元素对应一张子表元素的多个 PI Point 属性变成一行中的多个列。文件结构多列模型配置文件由一个或多个超级表定义块组成块与块之间用空行分隔。每个超级表定义块包含行格式说明超级表名SuperTable,名称TDengine 超级表名称子表名规则SubTable,模板支持占位符如${element_name}_${element_id}元素模板Template,模板名对应 PI AF 中的元素模板名称过滤条件Filter,条件可选用于过滤元素列定义列名,KEY\|COLUMN\|TAG,数据类型,映射规则定义每一列的映射列定义说明列定义行的第二列是关键字决定该列的角色列类型关键字说明时间戳列KEY必须有且仅有一个数据类型为TIMESTAMP数据列COLUMN对应 PI Point 属性的值Metric 列标签列TAG对应元素的静态属性或元数据这与 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定义超级表名为metertemplateSubTable,${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/statuselement_id,TAG,VARCHAR(100),$element_id标签列取元素的唯一 IDpath,TAG,VARCHAR(100),$path标签列取元素在 AF 层级中的路径两个细节值得注意status 列与 value 列成对出现PI 的每个数据点都带有质量状态good/bad/uncertain 等将其落为INT列入库后后续可以用 TAG/列查询数据可信区间这是工业数据落库的常见做法。列名做了 TDengine 合法化处理farm_lifetime_production__weekly_这类列名用双下划线和尾下划线替代了 PI 属性名中的空格/特殊字符。从示例可以看出列名必须满足 TDengine 标识符规则PI 属性名中的非法字符要在映射规则里显式处理。默认映射规则对于使用 AF Server 的多列模型任务taosX 生成默认配置时遵循的规则是PI Point 属性可产生时序值的属性默认映射为 TDengineCOLUMNMetric 列其他属性静态属性默认映射为 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_Voltagevalue,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_float32Meter_1000004_Current,POINT,milliampere_float32点位Meter_1000004_Current归属于超级表milliampere_float32从点位命名Meter_1000004_Voltage/_Current可以看出该场景来自电力计量同一块电表下电压、电流点位分属不同 UOM因此被默认配置分入不同超级表。若希望进一步按资产归组可直接修改POINT行引用的超级表名。映射规则与表达式常用占位符以下占位符可在列定义的映射规则中使用占位符说明适用范围$ts数据时间戳单列/多列$value点位值单列模型$status质量状态码单列/多列$point_namePI Point 名称单列模型$element_nameAF 元素名称多列模型$element_idAF 元素唯一 ID多列模型$path元素/点位路径单列/多列$categoriesAF 元素分类多列模型$element_paths点位关联的元素路径单列模型$属性名PI Point 属性或 AF 元素属性按实际属性名引用$属性名是最灵活的一类多列模型中它引用 AF 元素的属性PI Point 属性映射为 COLUMN静态属性映射为 TAG见上文“默认映射规则”单列模型中$ptclassname、$sourcetag、$engunits等实际上都是 PI Point 的属性名按需引用即可。内联表达式对于需要数据转换的场景映射规则列可以用反引号包裹内联表达式element_paths,TAG,VARCHAR(512),$element_paths.replace(\\, .)表达式内部支持对字符串字段调用处理方法如replace占位符先取源值、再执行表达式、最后写入目标列。这与 TDengine 零代码写入平台内置 ETL 的“转换/映射”能力一脉相承更完整的映射规则与表达式语法解析、过滤、映射、格式化处理函数、数学表达式等请参阅 零代码数据写入 的“数据提取、过滤和转换”部分。子表名占位符SubTable行的模板支持以下占位符占位符说明${point_name}PI Point 名称单列模型${element_name}AF 元素名称多列模型${element_id}AF 元素唯一 ID多列模型占位符可以组合使用如${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 ...。过滤特定点位或模板两种操作路径下载前过滤在 taosExplorer 中先填写 Dataset Filter再点击下载默认配置生成的配置就只包含匹配范围。Filter 的可用单位取决于连接方式与数据模型point/element/template支持*、?通配符完整语法见 Dataset Filter 配置。下载后手动编辑 CSV多列模型修改超级表定义块中的Filter行该行的值就是生成时使用的 Dataset Filter单列模型在点位映射部分删除不需要的POINT行。注意一个容易踩的坑AF Server 模式下的单列模型Dataset Filter 只支持element/template而不支持point——因为 AF 单列需要经由 Element → Attribute 上下文获取 UOM、元素归属等元数据直接用点位名过滤会丢失这些信息。自定义超级表名如果默认按 UOM 分组的命名不满足需求例如希望按产线、区域或资产类别组织超级表可以直接修改SuperTable行的值并同步调整点位映射部分引用的超级表名多列模型则修改Template行关联的模板名并调整列定义即可。修改后上传覆盖默认配置任务重启生效。与任务配置的关系配置文件中没有的东西模型配置文件只负责“映射”其他运行时参数在 taosExplorer 的任务配置中完成理解两者的边界有助于排错配置域所在位置典型配置项连接信息taosExplorer 连接区域PI 服务名、AF Server 名、AF 数据库名Windows 集成认证下 Username/Password/Domain 留空Backfill 参数taosExplorer 任务区域实时任务的重启补偿时间如 2d/3h回填任务的开始/结束时间高级选项taosExplorer 高级区域连接器日志级别默认info、批次大小默认 1000、批次延时默认 1s、写入队列长度默认 1000、写入错误阈值默认 10等映射结构模型配置文件本文主题超级表/子表/列映射、Filter、转换表达式另外PI 连接器依赖 PI AF SDK仅支持 Windows 环境网络侧需放通 5450Data Archive与 5457AF 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考