Skip to content

docs: drop unsupported %k from date specifier table - #6140

Open
prql-bot wants to merge 1 commit into
mainfrom
docs/date-specifier-k
Open

docs: drop unsupported %k from date specifier table#6140
prql-bot wants to merge 1 commit into
mainfrom
docs/date-specifier-k

Conversation

@prql-bot

@prql-bot prql-bot commented Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Problem

The date-specifier table in web/book/src/reference/stdlib/date.md is introduced as "the list of the specifiers currently supported", but %k is rejected by every dialect:

$ prqlc compile <<'EOF'
prql target:sql.postgres
from tbl
select {a = (tbl.col | date.to_text "%k")}
EOF
Error:
   ╭─[ :3:37 ]
   │
 3 │ select {a = (tbl.col | date.to_text "%k")}
   │                                     ──┬─
   │                                       ╰─── PRQL doesn't support this format specifier
───╯

chrono parses %k (and %_H) as Item::Numeric(Numeric::Hour, Pad::Space), and no dialect's translate_chrono_item in prqlc/prqlc/src/sql/dialect.rs has a Pad::Space arm — Pad::None and Pad::Zero are handled everywhere, so every space-padded specifier falls through to the unsupported-specifier error.

Solution

Docs-side fix rather than implementing space padding: no target has a direct space-padding template (Postgres would need LPAD(TO_CHAR(...), 2, ' ') rather than a format string, and MySQL's own %k is the no-pad hour, already used for Pad::None), so implementing it is a design decision rather than a doc correction.

  • Drop the %k row, and note under the table that space-padded specifiers aren't supported by any dialect — so someone coming from chrono's docs isn't left guessing.
  • Add a %-H row in its place. It is supported (TO_CHAR(col, 'FMHH24') on Postgres) but wasn't documented, even though the sibling %-m and %-d rows are.

Testing

Adds test_date_format_specifiers_compile to the book documentation tests, which parses the specifier table out of date.md and compiles each row against sql.postgres. This is the durable part: the table can't silently drift from the dialect implementations again. It has a floor check on the row count so it can't pass vacuously if the table's formatting changes.

Confirmed the test fails on main with exactly one error (%k) and passes with the docs fix. Full cargo test -p mdbook-prql --test documentation is green (6 passed).

Note: #6138 also edits this table (a wrong %-d example) — different row, no overlap.


Closes #6139 — automated triage

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs list %k as a supported date.to_text specifier, but every dialect rejects it

1 participant