docs(sql): complete the window-function list, and guard it with a test

[fupelaqu]

What

documentation/sql/dql_statements.md enumerates which functions work with OVER. That list had fallen four entries behind the parser: identifierWithWindowFunction accepts 14 forms, the list named 10 — omitting AVG, MIN, MAX and PERCENTILE_CONT / PERCENTILE_DISC.

The reference page (functions_aggregate.md) documents all of them, and so do keywords.md and the REPL help JSON. So this was an enumerated list going stale, not a missing feature — but the DQL page is where a reader goes to find out what works with OVER, and it was the one saying no.

Found because the same omission had propagated into a blog post.

Verified, not read

Every added form was run through the real parser before being written down, and each is asserted to round-trip — statement.sql must parse again. A round-trip that silently drops a clause is how a documented form becomes a wrong query downstream.

The percentile forms turned up something worth documenting on its own: all four spellings normalize to the same canonical rendering. Writing

PERCENTILE_CONT(0.95) OVER (PARTITION BY service ORDER BY ms)

gets you back

PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY ms) OVER (PARTITION BY service)

Same for the (column, p) shorthand. A statement round-tripped through the engine returns in a syntax the user did not type — that is now stated in the docs.

The test

WindowFunctionCoverageSpec — 32 tests, green (plus 532 sql tests and scalafmtCheck).

Every form is pinned to its exact rendering, not to "it parses". That distinction is the whole point, and the first revision of this PR got it wrong: Parser(rendered).isRight proves a rendering parses, not that it is faithful — and the suite already contained the counter-example. ARRAY_AGG's inline LIMIT is parsed, kept on the AST, and silently dropped when rendering (emitsLimitInOver is false for everything but ranking windows). The weaker assertion was green on precisely the corruption it was written to catch.

• 28 documented forms, each pinned to the string the engine gives back
• 1 named test for the ARRAY_AGG LIMIT loss, so the day it is fixed the suite says so instead of staying quietly green
• 3 rejections, each asserting why. ROW_NUMBER() OVER (PARTITION BY d) and ROW_NUMBER() AS rn are rejected with the same generic message, so isLeft alone could not tell "the ANSI rule fired" from "ROW_NUMBER stopped being a window function"; it is now paired with the ORDER BY variant that must parse. The percentile rejections assert the message names the [0,1] bound.

Corrections from review

• PERCENTILE_DISC(p) OVER (...) was listed and does not parse — the value column is required, so ORDER BY inside OVER is not optional
• SUM/AVG/MIN/MAX/COUNT now show OVER (PARTITION BY ...): an ORDER BY inside a non-ranking OVER is accepted and then discarded (COUNT(x) OVER (PARTITION BY c ORDER BY ts) renders back without it)
• the percentile "See" link pointed at another page while this file has its own percentile section
• the first commit did not pass sql/Test/scalafmtCheck — verified by restoring it and running the gate

Not included

softclient4es-web's src/content/docs/sql/dql.mdx carries the same section and the same gap. That is a separate PR on the web repo.

🤖 Generated with Claude Code