Skip to main content

Date & time axes

kuva's axes are numeric: a time axis is just numbers. x_datetime and y_datetime tell the renderer to treat one axis's values as Unix timestamps in seconds and lay its ticks out as calendar dates.

FieldTypeWhat it sets
unitstringThe tick spacing's calendar unit: "auto" · "year" · "month" · "week" · "day" · "hour" · "minute" · "second".
stepintegerHow many units between ticks (default 1).
formatstringA strftime-style label format, e.g. "%Y-%m-%d". Required unless unit is "auto".

The values themselves still come from the data, so feed the series an epoch-seconds column — epoch(date_column) in DuckDB.

Making a timestamp​

DuckDB can produce the seconds for you, whatever the source column looks like:

ColumnWhat to pass as the coordinate
DATEepoch(CAST(d AS DATE))
TIMESTAMPepoch(ts)
A stringepoch(strptime(s, '%Y-%m-%d %H:%M:%S'))
Already an epoch in msdivide by 1000 before plotting

Units and formats​

unitTick everyA format that fits
"year"one year"%Y"
"month"one month"%b %Y"
"week"one week (Mondays)"%b %d"
"day"one day"%Y-%m-%d"
"hour"one hour"%H:%M"
"minute"one minute"%H:%M"
"second"one second"%H:%M:%S"

step: 2 on a monthly axis puts a tick every second month, and so on.

Example​

A closing price over time, one tick a month:

SELECT kuva_render(to_json({
'x_datetime': {'unit': 'month', 'step': 1, 'format': '%Y-%m'},
'x_axis': {'name': 'date'},
'y_axis': {'name': 'close'},
'series': [{'type': 'line', 'data': pts, 'color': '#4c72b0', 'fill': true, 'fill_opacity': 0.1}]
})) AS chart
FROM (
SELECT array_agg({'x': epoch(CAST(date AS DATE)), 'y': close} ORDER BY date) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/candlestick.tsv')
);

Letting kuva choose — "unit": "auto"​

If you do not know the span ahead of time, hand the axis its range and let kuva pick the unit and the format:

SELECT kuva_render(to_json({
'x_datetime': {'unit': 'auto'},
'x_axis': {'name': 'date', 'min': 1704067200, 'max': 1735689600},
'y_axis': {'name': 'close'},
'series': [{'type': 'line', 'data': pts, 'color': '#4c72b0'}]
})) AS chart
FROM (
SELECT array_agg({'x': epoch(CAST(date AS DATE)), 'y': close} ORDER BY date) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/candlestick.tsv')
);

auto needs to know the axis range: either give the axis both min and max (as above) or let the series publish a range — which every plot backed by data does. format and step are ignored in this mode; for the named units format is required, and a missing one is reported as an error rather than guessed at.

On the y axis​

y_datetime works exactly like x_datetime, for charts where time runs vertically — a Gantt chart, a timeline of samples:

{ "y_datetime": {"unit": "day", "format": "%Y-%m-%d"} }

Notes​

  • Values are seconds, not milliseconds and not dates. A millisecond epoch plots as a date some 50 000 years in the future, which shows up as a blank or wildly-scaled axis rather than an error.
  • format is required for the named units — kuva writes the tick labels with it (strftime syntax as used by chrono), so there is nothing sensible to fall back on.
  • Coarser units read better. Sub-day units over a long span produce tick labels that collide; use auto, or a unit one step coarser.
  • A date axis is independent of the axis label: x_axis.name still names it, and math in labels works there too.

See also​