docs: document date.diff in the date functions page

[prql-bot]

The date functions page opens with "These are all the functions defined in the date module", but documents only to_text, now and trunc. date.diff, added in #5726, was never listed — so the page's completeness claim has been wrong since that merged. This documents it.

Every dialect row was produced by compiling the example rather than transcribed from the test file, and the new prql block is covered by the book's own snapshot test (documentation__book__reference__stdlib__date__date-functions__5.snap), which is the regression test for the page: cargo test --test documentation passes 7/7 without --accept.

How the documented behavior was verified

The section is appended after trunc rather than inserted in stdlib order on purpose — book snapshots are numbered by position within the page, so inserting mid-page would renumber date-functions__0..4 and churn five unrelated snapshot files for no benefit. Appending makes the new block index 5 and leaves the existing five untouched, which git status confirms.

Dialect outputs, each from prqlc compile on from events | derive { days_open = (date.diff day start_date end_date) } with the corresponding prql target:sql.<dialect> header:

duckdb     => datediff('day', start_date, end_date)
mssql      => DATEDIFF(day, start_date, end_date)
mysql      => TIMESTAMPDIFF(day, start_date, end_date)
clickhouse => dateDiff('day', start_date, end_date)
bigquery   => DATE_DIFF(end_date, start_date, day)
snowflake  => DATEDIFF(day, "start_date", "end_date")
postgres   => error: operator std.date.diff is not supported for dialect postgres
sqlite     => error: operator std.date.diff is not supported for dialect sqlite

Two points the page now makes that are easy to get wrong:

• The unit is a bare keyword. std.prql:264 declares it as `noresolve.unit`, unlike trunc's unit<text>. Since the argument is unresolved, writing it as a string is not rejected — it is passed through verbatim, so date.diff "day" a b emits DATEDIFF('day', a, b), which the quoting-sensitive dialects will not accept. Documenting the keyword form keeps readers off that path.
• Rounding is not normalized by PRQL. The dialects disagree — MSSQL's DATEDIFF counts boundary crossings while MySQL's TIMESTAMPDIFF truncates toward zero — so the page attributes the behavior to the target database rather than stating a single rule that would be wrong for half the table.

Formatting checked with prettier@3.9.6 --check (the version pinned in .pre-commit-config.yaml), which passes.

[prql-bot]

Self-authored, so this is a COMMENT rather than an approval.

Checked every dialect row against std.sql.prql and the existing cases in prqlc/prqlc/tests/integration/sql.rs (date_diff_operator, date_diff_snowflake, date_diff_unsupported_dialects) — all seven match, MSSQL and Snowflake correctly falling through to the generic DATEDIFF. The noresolve.unit vs unit<text> contrast against date.trunc matches std.prql, the snapshot index of 5 follows the five existing blocks on the page, and the page's opening "these are all the functions" claim is true again now that the date module's fourth function is listed.

Two things about the prose:

The section never states the argument order or the sign of the result. unit is referenced in the first sentence but no signature appears anywhere, so the only way to learn that date.diff takes unit start end — and that the result is end minus start — is to infer it from the days_open variable name in the example. Every dialect implementation agrees on that direction, so it's a safe thing to say outright. The suggestion also notes that the accepted units follow the target database, which is the other question a reader arrives with and the page currently doesn't answer.

The note's rationale is broader than what's true. Postgres does have date-difference facilities — AGE(), and plain subtraction on date values — it just has no DATEDIFF, which is how std.sql.prql's own comment scopes it ("PostgreSQL has no built-in DATEDIFF equivalent"). As written, a Postgres reader may conclude the operation is unavailable rather than that this particular spelling is.

Both edits stay within proseWrap: always at 80 columns — verified with prettier@3.9.6, the version pinned in .pre-commit-config.yaml.