Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
194 lines
9.2 KiB
Markdown
194 lines
9.2 KiB
Markdown
# Retrieval options (the rest of the `wwXxx` parameters)
|
||
|
||
`wwRetrievalMode` picks the algorithm; everything below tunes it. Set in the `WHERE` clause exactly like `wwRetrievalMode`. Each is case-insensitive. None can be supplied via `IN` or `OR`.
|
||
|
||
## Which option applies to which mode
|
||
|
||
(Selecting the most-asked questions; consult the source PDF table on pp. 89-90 for the full grid.)
|
||
|
||
| Option | Cyclic | Delta | Full | Interpolated | BestFit | Average | Min | Max | Integral | Slope | Counter | ValueState | RoundTrip |
|
||
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||
| `wwCycleCount` | ✅ | (limit) | – | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| `wwResolution` | ✅ | – | – | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| `wwTimeDeadband` | – | ✅ | – | – | – | – | – | – | – | – | – | – | – |
|
||
| `wwValueDeadband` | – | ✅ | – | – | – | – | – | – | – | – | – | – | – |
|
||
| `wwVersion` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| `wwInterpolationType` | – | – | – | ✅ | ✅ | ✅ | – | – | ✅ | ✅ | – | – | – |
|
||
| `wwTimeStampRule` | ✅ | – | – | ✅ | – | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| `wwQualityRule` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| `wwStateCalc` | – | – | – | – | – | – | – | – | – | – | – | ✅ | ✅ |
|
||
| `wwFilter` (analog filter) | ✅ where applicable | – | – | ✅ | ✅ | ✅ | – | – | – | – | – | – | – |
|
||
| `wwValueSelector` (summary tags) | ✅ | – | – | – | – | – | – | – | – | – | – | – | – |
|
||
| `wwTimeZone` | ✅ everywhere |
|
||
| `wwEdgeDetection` | – | – | – | – | – | – | – | – | – | – | – | – | ✅ |
|
||
|
||
## `wwCycleCount` — number of cycles
|
||
|
||
```sql
|
||
AND wwCycleCount = 60 -- give me 60 evenly-spaced cycles across the window
|
||
```
|
||
|
||
For "truly cyclic" modes (`Cyclic`, `Interpolated`, `Average`, `Integral`) you get one row per tag per cycle. Other modes use cycles for grouping but may emit zero, one, or many rows per cycle.
|
||
|
||
For `Delta` / `Full`, `wwCycleCount` acts as a **limit on the first N matching rows** instead of a cycle count.
|
||
|
||
`wwCycleCount` and `wwResolution` are mutually exclusive intents — set one. If neither is set, the default cycle count is **100**.
|
||
|
||
## `wwResolution` — cycle length in milliseconds
|
||
|
||
```sql
|
||
AND wwResolution = 60000 -- 60-second cycles
|
||
```
|
||
|
||
`number_of_cycles = window_length / wwResolution`. Use this when "every minute" matters more than "100 evenly-spaced points." See "Phantom cycles" in the source PDF (p. 95) for what happens at the boundary edges.
|
||
|
||
## `wwTimeDeadband` — suppress fast changes (Delta only)
|
||
|
||
Milliseconds. Within `wwTimeDeadband` of the most recently returned point, further changes are dropped. The deadband resets every time a point is emitted.
|
||
|
||
```sql
|
||
AND wwRetrievalMode = 'Delta' AND wwTimeDeadband = 10000 -- ≤1 sample / 10 s
|
||
```
|
||
|
||
## `wwValueDeadband` — suppress small changes (Delta only)
|
||
|
||
Percent of the tag's engineering-unit full-scale. Drops changes smaller than the deadband from the previously returned point. Quality changes always force a row out, regardless of deadband.
|
||
|
||
```sql
|
||
AND wwRetrievalMode = 'Delta' AND wwValueDeadband = 1.0 -- 1% of full scale
|
||
```
|
||
|
||
## `wwVersion` — original vs. latest stored value
|
||
|
||
```sql
|
||
AND wwVersion = 'Latest' -- default; honors any post-write corrections
|
||
AND wwVersion = 'Original' -- as captured at write time
|
||
```
|
||
|
||
Latest values that have been overwritten carry `QualityDetail = 202`. Applies to every retrieval mode.
|
||
|
||
## `wwInterpolationType`
|
||
|
||
```sql
|
||
AND wwInterpolationType = 'Linear' -- override per-query
|
||
AND wwInterpolationType = 'StairStep'
|
||
```
|
||
|
||
Resolution order: query-level `wwInterpolationType` > per-tag `AnalogTag.InterpolationType` > system parameters `InterpolationTypeInteger` / `InterpolationTypeReal`. The output column also reports the type that was actually applied per row (`LINEAR` or `STAIRSTEP`).
|
||
|
||
## `wwTimeStampRule` — which end of the cycle owns the timestamp
|
||
|
||
```sql
|
||
AND wwTimeStampRule = 'START' -- default; row stamped at cycle start
|
||
AND wwTimeStampRule = 'END' -- row stamped at cycle end
|
||
```
|
||
|
||
Affects the `DateTime` column in cyclic-flavored modes. Cycle-start time is also exposed via the read-only `StartDateTime` column for diagnostic purposes (cannot be used in `WHERE` — see [`02-syntax-limits.md`](02-syntax-limits.md)).
|
||
|
||
## `wwTimeZone` — return data in a different zone
|
||
|
||
Accepts any value from the `TimeZone.TimeZone` column. The `TimeZone` table is rebuilt at every server start from the OS's registered zones, so it picks up custom zones automatically. DST is corrected against the **server** OS; there is no client-side zone option.
|
||
|
||
```sql
|
||
AND wwTimeZone = 'Eastern Standard Time'
|
||
```
|
||
|
||
If unset, the server's local zone is used. For UTC-only output use `wwTimeZone = 'UTC'`.
|
||
|
||
## `wwQualityRule` — how to combine quality
|
||
|
||
When combining multiple stored points into one cycle output (any cyclic mode plus `Average`, `Min`, `Max`, etc.), this controls how individual qualities collapse into a single output quality:
|
||
|
||
- `Good` (default for most cyclic modes) — output is Good only if every contributing point was Good.
|
||
- `Extended` — propagate worst quality with extra detail bits.
|
||
- Other rule names per source PDF p. 111. Eight worked queries on pp. 113-118.
|
||
|
||
`Cyclic`, `Full`, `Delta`, `Min`, `Max`, `BestFit` do **not** combine qualities — `wwQualityRule` is silently ignored for those.
|
||
|
||
## `wwStateCalc` — `ValueState` / `RoundTrip` aggregation
|
||
|
||
For `ValueState`:
|
||
|
||
- `Minimum` — shortest time in each unique state.
|
||
- `Maximum` — longest time in each unique state.
|
||
- `Average` — average time in each unique state.
|
||
- `Total` — total time in each unique state.
|
||
- `Percent` — total time as a percentage of cycle length.
|
||
|
||
For `RoundTrip`, only the `*Contained` variants are valid: `MinContained`, `MaxContained`, `AvgContained`, `TotalContained`, `PercentContained`. The "contained" forms only count fully-contained intervals — partial intervals at cycle boundaries are excluded, which matters for slow-changing tags vs. long cycles. The non-contained calculations have arbitrary cycle-boundary effects that can produce non-intuitive results for slow tags over long cycles.
|
||
|
||
## `wwFilter` — analog value filtering
|
||
|
||
Three filter functions, plus the predictive variant.
|
||
|
||
- `SigmaLimit(<n>)` — drop outliers more than *n* standard deviations from the mean.
|
||
- `ToDiscrete(<threshold>, <op>)` — convert analog to discrete; e.g. `ToDiscrete(5.0, >)` returns 1 above 5.0, 0 below. Supported ops: `>`, `>=`, `<`, `<=`, `=`, `<>`.
|
||
- `SnapTo(<step>, <min>, <max>)` — quantize the value to the nearest `step`, clamped to `[min, max]`. Snapped values get the `0x2000` `QualityDetail` bit.
|
||
- Predictive variant — see source PDF p. 86; SLR forecast over the cycle.
|
||
|
||
```sql
|
||
AND wwFilter = 'SnapTo(0.01, 0, 1000)'
|
||
AND wwFilter = 'ToDiscrete(5.0, >)'
|
||
```
|
||
|
||
Bad filter syntax returns a syntax error and zero rows.
|
||
|
||
## `wwValueSelector` — analog summary value pickoff
|
||
|
||
When an analog summary tag has multiple summarized values stored for one period, this picks which one to surface:
|
||
|
||
| Setting | Meaning |
|
||
| --- | --- |
|
||
| `AUTO` (default) | Mode-dependent — see PDF p. 125-128. |
|
||
| `FIRST` | First summarized value in the period. |
|
||
| `LAST` | Last value in the period. |
|
||
| `MIN` | Minimum value in the period (timestamp = where the min occurred). |
|
||
| `MAX` | Maximum value in the period (timestamp = where the max occurred). |
|
||
| `AVG` | Time-weighted average. |
|
||
|
||
## `wwEdgeDetection` (RoundTrip + alarm/event subqueries)
|
||
|
||
Picks which edges count for `RoundTrip`:
|
||
|
||
```sql
|
||
AND wwEdgeDetection = 'Leading' -- transition into the state
|
||
AND wwEdgeDetection = 'Trailing' -- transition out of the state
|
||
AND wwEdgeDetection = 'Both' -- either
|
||
```
|
||
|
||
Also used in event-pattern queries against the `WideHistory` table — see PDF pp. 78-85 for analog and discrete edge-detection examples.
|
||
|
||
## `wwOption` — reserved bit-bag
|
||
|
||
Catch-all for one-off feature flags AVEVA exposes per release. Almost never set in user queries; consult the source PDF if a feature note tells you to.
|
||
|
||
## Reserved / deprecated
|
||
|
||
| Name | Status |
|
||
| --- | --- |
|
||
| `wwParameters`, `wwMaxStates` | Reserved. Don't use. |
|
||
| `wwRowCount` | Deprecated alias for `wwCycleCount`. Still works, but write new queries with `wwCycleCount`. |
|
||
|
||
## Combining options
|
||
|
||
Multiple `wwXxx` are fine as long as each appears in a single `AND` predicate (no `IN`, no `OR`). A representative dense query:
|
||
|
||
```sql
|
||
SELECT TagName, DateTime, Value, StateTime, StartDateTime
|
||
FROM History
|
||
WHERE TagName IN ('Reactor1Level')
|
||
AND DateTime >= DATEADD(hour, -8, GETDATE()) AND DateTime <= GETDATE()
|
||
AND wwRetrievalMode = 'RoundTrip'
|
||
AND wwStateCalc = 'AvgContained'
|
||
AND vValue = CONVERT(SQL_VARIANT, '1')
|
||
AND wwCycleCount = 1
|
||
AND wwTimeStampRule = 'Start'
|
||
AND wwQualityRule = 'Good'
|
||
AND wwFilter = 'ToDiscrete(5.0,>)'
|
||
AND wwVersion = 'Latest';
|
||
```
|
||
|
||
## Next
|
||
|
||
- [`05-query-recipes.md`](05-query-recipes.md) — when these options come together to answer specific questions.
|