📚 课程目录第2章 PI Data Archive数据模型与访问基础

2. PI Data Archive数据模型与访问基础

PI Data Archive 是 PI System 的时序数据核心，它并不是一个“按行存储的普通数据库”，而是围绕 PI Point（位号） 组织的时间序列存储。理解 PI Point 的类型、属性、时间戳与质量码，是后续做计算分析、实时指标开发的前提。本节先建立数据模型认知，再落到 PI SDK 与 PI Web API 两种访问方式，最后用 PI System Explorer 实际浏览数据。

一、PI Point 的四种数值类型

每个 PI Point 都有一个 PointType，它决定了该位号能存什么、怎么解释。常见类型如下：

Float（浮点型）：最常用，存储连续测量值，如温度 78.35 ℃、流量 120.6 t/h、压力 1.024 MPa。内部为 32 位浮点，适合模拟量。
Int（整型）：存储 32 位整数，如计数器读数、批次号、累计次数。注意它不能存小数，若把流量建成 Int 会丢失精度。
Digital（数字状态型）：存储离散状态，如 0=停、1=运行、2=故障。它通常配合 Digital Set（状态集）使用，把数字翻译成可读文本。
String（字符串型）：存储文本，如批次号 “B20240612-07”、设备编码。String 位号一般不参与数值计算。
Timestamp（时间戳型）：存储时间点本身，如“上次检修时间”。它常用于记录事件时刻，而不是测量值。

选择类型的原则很简单：能算的用 Float/Int，能枚举的用 Digital，只做标识的用 String，只记时刻的用 Timestamp。类型一旦建错，后期改类型往往需要重建位号，代价较高。

二、必须理解的五个核心属性

PI Point 的属性很多，但以下五个直接决定数据质量和计算行为：

属性	含义	示例
Zero	量程下限，用于换算和百分比显示	0
Span	量程跨度，与 Zero 共同定义量程	100
EngUnits	工程单位，仅作标识，不参与换算	℃、t/h、MPa
ExcDev	例外偏差，超过该偏差才记录到档案	0.5
CompDev	压缩偏差，超过该偏差才保留历史值	0.1

这里要区分两个概念：ExcDev（Exception Deviation） 作用于接口层，决定“新值是否值得送进 PI”；CompDev（Compression Deviation） 作用于归档层，决定“历史值是否值得保留”。两者都设得过大，会丢失真实波动；设得过小，会产生大量冗余数据。工程上常按量程的 0.1%～1% 估算，例如量程 0～100 ℃，CompDev 可取 0.1 ℃。

Zero 与 Span 还影响 % 量程显示：百分比 = (当前值 − Zero) / Span × 100%。若 Zero=0、Span=100，当前值 75 即 75%。

三、时间戳与质量码

PI 中每个值都是 (时间戳, 值, 质量码) 三元组。时间戳默认是 UTC 存储、按客户端时区显示，做跨时区分析时必须统一参照系。质量码（Quality）常见取值：

Good：正常采集值，可放心参与计算。
Bad：采集失败或无效，计算时应剔除或标记。
Questionable：可疑，如超量程、通信抖动，需人工确认。
Substituted：人工替换值，常用于补数，分析时要能识别。

做实时指标时，不能只看数值，必须同时判断质量码。例如计算“平均温度”时，若把 Bad 值当 0 参与平均，结果会被严重拉低。

四、PI SDK 与 PI Web API 的访问方式

访问 PI Data Archive 主要有两条路径：

PI SDK：传统 COM 组件，适合 .NET/C++ 桌面程序，直接连接 PI Data Archive，性能好，但依赖 Windows 环境与客户端安装。
PI Web API：基于 REST/JSON 的现代接口，通过 HTTPS 访问，适合 Web、跨平台和云集成，天然支持批量读取与流式订阅。

以读取某位号一段时间的历史值为例，PI Web API 的典型请求如下：

GET https://{server}/piwebapi/streams/{webId}/recorded
    ?startTime=2024-06-12T08:00:00Z
    &endTime=2024-06-12T09:00:00Z
    &maxCount=1000

返回 JSON：
{
  "Items": [
    { "Timestamp": "2024-06-12T08:00:05Z", "Value": 78.35, "Good": true },
    { "Timestamp": "2024-06-12T08:00:35Z", "Value": 78.41, "Good": true }
  ]
}

其中 webId 是位号的唯一标识，可通过 /piwebapi/points?path=\\PIServer\TagName 获取。PI SDK 则通过 PIServer.Connect、PIPoint.Data.RecordedValues 等方法读取，逻辑类似，只是调用形式不同。

五、用 PI System Explorer 浏览数据

PI System Explorer 是查看数据模型最直观的工具。打开后连接目标 PI Data Archive，在左侧导航中展开 Data → Points，即可看到位号列表。选中某个位号，右侧会显示其属性页（PointType、Zero、Span、EngUnits、ExcDev、CompDev 等），切换到 Current Value 可看当前值与质量码，切换到 Archive 或 Trend 可查看历史曲线。

实际操作中，建议先按类型或模板筛选位号，再逐个核对属性。例如发现某温度位号 EngUnits 为空、CompDev 为 0，就应补全单位并设置合理压缩偏差，否则历史数据会异常密集或异常稀疏。

六、一个可复用的位号检查清单

在正式做计算分析前，建议对每个关键位号做一次快速核对。以下清单可直接用于日常检查：

检查项	合格标准	常见问题
PointType	与物理量匹配	流量误建为 Int
Zero / Span	覆盖实际量程	Span 过小导致超量程
EngUnits	单位正确且统一	℃ 与 K 混用
ExcDev / CompDev	按量程 0.1%～1% 设置	CompDev=0 导致数据爆炸
质量码	Good 占比正常	大量 Bad 未处理
时间戳	时区一致	UTC 与本地时间混用

做实时指标前，先用 PI System Explorer 抽查 3～5 个关键位号的属性与质量码分布，往往能提前发现 80% 的数据问题。

掌握以上内容后，后续无论是用 PI SDK 写采集程序，还是用 PI Web API 做 Web 端指标展示，都能清楚知道“数据从哪来、是什么类型、质量如何、该怎么读”。这是 PI System 计算分析与实时指标开发最基础、也最不能跳过的一步。