historian_query
Read-only
Fetch historical tag samples from SQLite, TDengine, or IoTDB to inspect pre-incident windows for root cause analysis. Read-only, bounded rows with truncation flag.
Instructions
[READ][risk=low] Query a tag's historical samples from a historian.
Reads history back OUT of the store the sinks write — the local SQLite
store (~/.iaiops/data.db), TDengine, or IoTDB — so the RCA copilot / an
agent can see real pre-incident windows instead of only short live samples.
Read-only over the operator's OWN historian; no device I/O. Bounded: rows
are capped and a truncation flag is set when more history exists.
Args:
tag: Tag/metric name as stored by historian_push (e.g. 'line1.temp').
since/until: Optional ISO-8601 time bounds (inclusive).
endpoint: Only samples from this endpoint label (sqlite reader only —
the TSDB layout stores no endpoint label).
reader: 'sqlite' | 'tdengine' | 'iotdb'. Omit to use the per-site
'historian:' block in ~/.iaiops/config.yaml, else the local sqlite
store. TSDB readers need their extra: pip install iaiops[tdengine|iotdb].
limit: Max rows returned (1..10000; default 1000).
Returns dict: {reader, source, tag, since, until, rows,
samples:[{ts, endpoint, protocol, tag, value, quality, unit}], truncated}
plus the standard return envelope (items_returned, items_total,
items_total_is_exact, is_truncated, truncation_note). Trust
`is_truncated`: an empty `samples` with is_truncated=false means the
history really is empty, NOT that the result was cut short.
Example: historian_query(tag="line1.temp", since="2026-07-02T06:00:00Z",
until="2026-07-02T08:00:00Z").
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | ||
| limit | No | ||
| since | No | ||
| until | No | ||
| reader | No | ||
| endpoint | No |