formatDateTime
Format a DateTime as a string using strftime-style patterns.
Signature
formatDateTime(datetime: DateTime, format: String, [timezone: String]): StringReturns
String
What it does
Formats a DateTime value as a string using a format string with strftime-compatible directives. Used to produce human-readable date labels for charts and reports.
formatDateTime is the primary way to produce date strings for display. It supports all standard strftime directives: %Y (4-digit year), %m (month), %d (day), %H (hour), %M (minute), %S (second), %u (day of week 1-7), %W (week of year), and more. The time zone argument overrides the column's stored time zone for display purposes.
Notes
- For sorting, always sort on the underlying DateTime or toStartOfMonth — string sort of formatted dates can break for non-ISO formats.
- Use %F as a shorthand for %Y-%m-%d.
- The timezone argument is for display only — it does not change the stored value.
Example SQL
formatDateTime in ClickHouse SQL
TypeScript with hypequery
Use formatDateTime in a typed TypeScript query
hypequery gives you a type-safe query builder for ClickHouse. The generated schema maps your ClickHouse columns to TypeScript types, and raw SQL expressions let you incorporate functions like formatDateTime when you need them inside a builder query.
Common questions
What developers search for with formatDateTime
ClickHouse format date as string
formatDateTime(ts, '%Y-%m-%d') produces ISO date strings. Use '%b %Y' for labels like "Mar 2024" in charts.
FAQ
Frequently asked questions about formatDateTime
What format directives does formatDateTime support?
All standard strftime directives: %Y, %m, %d, %H, %M, %S, %u (weekday 1=Mon), %W (week), %j (day of year), %F (%Y-%m-%d shorthand), and more.
Related guides
Next step
Use formatDateTime in a type-safe TypeScript query
hypequery generates TypeScript types from your ClickHouse schema. Use formatDateTime alongside the builder, and reach for raw SQL expressions when the function is not exposed as a dedicated helper.