docs(historian): warn that QuestDB first()/last() ordering is implementation behaviour (#680 F1 review)

2026-10-11 18:48:53 -04:00
parent d266ff83f4
commit 8ebee2ac40
1 changed files with 6 additions and 0 deletions
@@ -101,6 +101,12 @@ internal static class QuestDbAggregateQueries
    ///         being written. One reference means one reader at one table version. A windowed (<c>row_number()</c>)
    ///         single-scan form was also correct but ~2× slower; this one is not slower than the old query.
    ///     </para>
+    ///     <para>
+    ///         ⚠️ <c>first()</c>/<c>last()</c> following timestamp order is QuestDB 10.0.1 IMPLEMENTATION behaviour (rows reach
+    ///         the GROUP BY in row-id order, and the parallel merge keeps row id), not a documented guarantee. It was verified
+    ///         on 20M rows with O3 inserts, single-threaded and parallel. Adding a JOIN, <c>ORDER BY</c> or <c>UNION</c> inside
+    ///         <c>Classified</c>, or upgrading QuestDB, can silently break Start/End — re-verify <c>first(ts) = min(ts)</c>.
+    ///     </para>
    /// </remarks>
    /// <param name="sample">Prefixed sample table name.</param>
    /// <returns>The SQL text.</returns>