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

id — internal identifier for the filter.
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.
bindings — object with date_from and date_to keys, overriding the parameter names the picker binds to. Use when one dashboard needs two date ranges bound to different model parameters.

Date tokens for defaults

The same set of tokens works on the from and to sub-keys (resolved against the workspace timezone — ui.timezone in workspace.yml — falling back to the instance default):

{{today}}
{{yesterday}}
{{start_of_week}} / {{end_of_week}}
{{start_of_month}} / {{end_of_month}}

Anything not in the list is treated as a literal ISO date string. When setting both defaults, keep from on or before to.

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.

The picker sends whole dates, with no time of day — when the column is a timestamp, compare against its date part (e.g. created_at::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: "{{start_of_month}}"
      to:   "{{today}}"

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: "{{today}}"

Filter — date_range