Type: explanation · Last reviewed: 2026-07-10
Every measurement Pulse Historian stores belongs to a collection — a group of time-series tags that share one location and one sampling interval. A collection is addressed by a four-part scope: organization / site / unit / grid. Understanding this 4-tuple is the key to everything else: writes, queries, alarms, backups, and access control all pivot on it.
If you read one concept page, read this one — the rest of the wiki assumes it.
| Level | What it is | Example |
|---|---|---|
| organization | The top-level tenant/customer | acme-power |
| site | A physical plant or location | plant-1 |
| unit | An asset or equipment train | boiler-2 |
| grid | A sampling group within the unit (one interval) | default_grid |
| tag | A single named signal (a sensor/point) | steam_pressure |
On disk, a collection is exactly this path: data/acme-power/plant-1/boiler-2/default_grid/, holding the binary time-series files plus a metadata.json. In PI System terms, a Pulse Historian tag ≈ a PI Point. See collection and scope in the glossary.
You can write and query using the full 4-tuple, or by tag name alone. Tag-name-only calls work because Pulse Historian keeps an in-memory map — the TAG_SCOPE_MAP — that it builds at startup by scanning the data/ tree, mapping each known tag to its scope. When you omit organization/site/unit/grid, Pulse Historian looks the tag up in that map. The map is refreshed when collections or tag mappings change.
Under the hood → Tag resolver (the filesystem scope mapper). (Note: the AI layer has a separate, unrelated semantic tag resolver — same file name, different job; the same page explains both.)
Using the canonical dataset (acme-power / plant-1 / boiler-2 / default_grid).
Write two tags at one timestamp (explicit scope):
POST /exactapi/write Authorization: Bearer <token>
{
"organization": "acme-power", "site": "plant-1",
"unit": "boiler-2", "grid": "default_grid",
"data": [
{ "timestamps": [1720008000000],
"tag_values": { "steam_pressure": 78.4, "steam_temp": 512.0 } }
]
}
// → 200
{ "status": "success", "written": 2 }
Query one tag back — by name only (scope resolved via TAG_SCOPE_MAP, so no 4-tuple needed):
POST /exactapi/fast_query Authorization: Bearer <token>
{ "tags": ["steam_pressure"], "start": 1720008000000, "end": 1720008120000 }
// → 200
{ "steam_pressure": { "timestamps": [1720008000000], "values": [78.4] } }
Exact request/response encodings (including the binary query formats) live in the API reference and API server. This page shows the JSON path for clarity.
orgs_id / sites_id / units_id, so permissions are enforced at scope boundaries.collection · scope · tag · TAG_SCOPE_MAP · grid