feat(historian): Part 13 time-weighted aggregates on SqlServer + QuestDb (#671)

New AggregateFamily.TimeWeighted serving TimeAverage, TimeAverage2, Total, Total2 and Interpolative, evaluated by the shared Sql.Common TimeWeightedAggregator for both SQL backends (identical results by construction). HistoryAggregateType gains TimeAverage2 + Total2 (appended); OtOpcUaNodeManager.MapAggregate maps their NodeIds. Gateway's mapper already refuses unknown defined members => BadAggregateNotSupported per node. Semantics (server defaults, client AggregateConfiguration ignored): TreatUncertainAsBad=false, PercentDataBad=PercentDataGood=100, UseSlopedExtrapolation=false. Sloped for Double/Int64, stepped for Boolean; a usable sample followed by a Bad one is held up to the outage (AtTime rule); stepped Uncertain extrapolation past the last sample. TimeAverage/Total use interpolated bounding (bridge outages); TimeAverage2/Total2 exclude Bad time. Bounding values: latest usable + latest any before start, first any + first usable at/after end (four TOP 1 / LIMIT 1 seeks). CLIENT-VISIBLE: Total on SqlServer/QuestDb was SUM of samples; it is now the time-weighted integral (TimeAverage x interval seconds), matching Gateway's Integral. Release note in docs/Historian.md. Trade-off (deviation from the preferred hybrid pushdown, allowed by the design): the time-weighted family is NOT pushed down. Each read streams the window's rows plus the four bounds (SQL Server: one five-result-set batch; QuestDB: bounds UNION ALL + window select) into the C# evaluator. Network is O(samples in window), memory O(buckets). Writing the per-segment interpolation/edge splitting twice in two SQL dialects and keeping them bit-identical was judged the bigger risk; this also makes the QuestDB lag/lead spike moot. Tests: 35 hand-computed TimeWeightedAggregator unit cases (each of 10 implementation mutations goes red); served-aggregate pin 13 -> 17; conformance sparse fixture (intervals wider and narrower than sample gaps) + an outage straddling both window edges (each of the four SQL seeks disabled in turn goes red); node-manager NodeId mapping test.
2026-10-11 08:44:26 -04:00
parent db6a53036b
commit 1f88669304
17 changed files with 1118 additions and 37 deletions
@@ -298,10 +298,12 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
    ///     <para>
    ///         Values: Count is <see cref="int"/>; Start/End keep the sample's type; every other aggregate is
    ///         <see cref="double"/> computed over <c>NumValue</c> (Boolean = 0/1). These are the simple per-sample
-    ///         definitions, not Part 13's interval-boundary (interpolated bound / time-weighted) semantics.
+    ///         definitions. The Part 13 time-weighted family (TimeAverage, TimeAverage2, Total, Total2, Interpolative, #671) is
+    ///         not pushed down: the window's rows plus four bounding rows are streamed into the shared
+    ///         <see cref="TimeWeightedAggregator"/>, which fills every interval (an empty one between bounds gets a value).
    ///     </para>
    /// </remarks>
-    /// <exception cref="HistoryAggregateNotSupportedException">The aggregate is not one of the thirteen served.</exception>
+    /// <exception cref="HistoryAggregateNotSupportedException">The aggregate is not one of the seventeen served.</exception>
    /// <exception cref="ArgumentOutOfRangeException">The window holds more than <see cref="MaxProcessedBuckets"/> intervals.</exception>
    public async Task<HistoryReadResult> ReadProcessedAsync(
        string fullReference, DateTime startUtc, DateTime endUtc, TimeSpan interval,
@@ -316,6 +318,14 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
            var now = _time.GetUtcNow().UtcDateTime;
            var evaluated = new Dictionary<long, DataValueSnapshot>();
            var tagId = plan.BucketCount == 0 ? null : await ResolveAsync(fullReference, cancellationToken).ConfigureAwait(false);
+            if (family == AggregateFamily.TimeWeighted)
+            {
+                var tw = new TimeWeightedAggregator(aggregate, plan);
+                if (tagId is { } twId) await StreamTimeWeightedAsync(twId, plan, tw, cancellationToken).ConfigureAwait(false);
+                var twResult = tw.Finish(now);
+                RecordSuccess();
+                return new HistoryReadResult(twResult, ContinuationPoint: null);
+            }
            if (tagId is { } id)
            {
                var sample = _conn.Q("Sample");
@@ -351,6 +361,25 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
        }
    }

+    /// <summary>
+    ///     Streams the time-weighted batch (<see cref="SqlAggregateQueries.TimeWeighted"/>) into <paramref name="tw"/>: the
+    ///     two before-bounds, the window, the two after-bounds — ascending, with duplicates dropped by the aggregator.
+    /// </summary>
+    private async Task StreamTimeWeightedAsync(int id, BucketPlan plan, TimeWeightedAggregator tw, CancellationToken ct)
+    {
+        await using var conn = await _conn.OpenAsync(ct).ConfigureAwait(false);
+        await using var cmd = _conn.CreateCommand(conn, SqlAggregateQueries.TimeWeighted(_conn.Q("Sample")));
+        cmd.Parameters.Add(new SqlParameter("@id", SqlDbType.Int) { Value = id });
+        SqlHistorianConnection.AddDateTime2(cmd, "@start", DateTime.SpecifyKind(plan.StartUtc, DateTimeKind.Utc));
+        SqlHistorianConnection.AddDateTime2(cmd, "@end", DateTime.SpecifyKind(plan.EndUtc, DateTimeKind.Utc));
+        await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+        do
+        {
+            while (await reader.ReadAsync(ct).ConfigureAwait(false))
+                tw.Add(ReadStored(reader, 0));
+        } while (await reader.NextResultAsync(ct).ConfigureAwait(false));
+    }
+
    private static BucketRow ReadBucket(SqlDataReader reader, AggregateFamily family)
    {
        static double? D(SqlDataReader r, int i) => r.IsDBNull(i) ? null : r.GetDouble(i);