Filter — date

When to use date_range

Use date_range for an open from / to date picker. The user picks both endpoints freely; the values are sent verbatim as parameters.

Use cutoff_date when the lower bound is always the start of the chosen date's month. Use date_range_preset when the user picks among named presets (last 30 days, this month, etc.) — preferred for most operational dashboards.

Required fields

type: date_range

Optional fields

label — display label above the picker.
default — object with from and to keys. Each accepts a date token (see below) or an ISO date string. Either or both may be omitted.

Date tokens for defaults

The same set of tokens works on the from and to sub-keys (resolved against the user's current timezone at page load):

Anything not in the list is treated as a literal ISO date string.

How the value reaches the Malloy query

The picker emits a {from, to} pair on submit. Looky sets two parameters on every query the filter applies to:

date_from — the chosen "from" date.
date_to — the chosen "to" date.

The Malloy model declares those parameters and uses them in where: clauses, exactly like with cutoff_date.

Adapter differences

Same date / timestamp caveat as cutoff_date — see the source adapter comparison for the Postgres / MySQL pattern.

Worked examples

Default to month-to-date:

filters:
  - type: date_range
    label: Period
    default:
      from: ""
      to:   ""

Default to a fixed historical period (for a frozen report):

filters:
  - type: date_range
    label: Period
    default:
      from: "2024-01-01"
      to:   "2024-12-31"

Default open to the current day, with no lower bound (the model's parameter default kicks in):

filters:
  - type: date_range
    label: Period
    default:
      to: ""

Common pitfalls

The query fails on Postgres or MySQL with a date-binding error. Add the @param placeholder pattern in the model's SQL — see the source adapter comparison.
"From" is later than "to". The picker prevents the user from picking an inverted range, but a default with from later than to renders an empty selection. Use a sensible default and let the user adjust.
Time-of-day precision matters but the picker is date-only. The picker only sends dates. Encode time-of-day in the Malloy query (e.g. compare against created_at::date) or use a different parameter pattern.
Multiple date_range filters in one viz. They all bind to date_from / date_to — only one wins. Either keep one date_range filter, or use date_range_preset with custom date_from_param / date_to_param bindings to use different parameter names.
The default tokens are not recognised. Only the listed tokens are valid; anything else is taken as a literal date string.

Filter — date_range