docs(driver.sql): topByTimestamp is only defined when the ordering column is unique (Driver.Sql-008)

This commit is contained in:
Joseph Doherty
2026-08-10 08:06:27 -04:00
parent 336e79ea9a
commit 9d4760fd2f
2 changed files with 20 additions and 2 deletions
+8
View File
@@ -80,6 +80,14 @@ the nested form.
}
```
⚠️ **`topByTimestamp` needs an ordering column that is unique per row.** It is executed as an
`ORDER BY <column> DESC` with the dialect's single-row limit, so when the column ties the server
returns an arbitrary row among the tied ones — and the driver cannot warn about it, because the other
rows were discarded before the result set reached it (the `whereColumn`/`whereValue` form *does*
warn, on `Rows.Count > 1`). A `date`-typed column ties for every row written on the same day, and
browse-commit will nominate one. Prefer a `datetime2`/sequence column that is unique per row, or
point the tag at a latest-row view.
`whereValue` may be authored as a JSON string, number or boolean (it is bound as a parameter either
way). `keyValue` on the `KeyValue` model must be a **string**.