# 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.
