wwtools/histdb/04-retrieval-options.md

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

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

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.

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.

AND wwRetrievalMode = 'Delta' AND wwValueDeadband = 1.0   -- 1% of full scale

wwVersion — original vs. latest stored value

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

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

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

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.

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.

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:

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:

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 — when these options come together to answer specific questions.