Filter — month

When to use month

Use month when the analysis is keyed on a single month — monthly close, monthly billing, comparable-month-over-comparable-month reporting. The user picks a year + month; the value is sent as a YYYY-MM string to the configured parameter.

Use a date filter (cutoff_date, date_range, date_range_preset) instead when the analysis spans an arbitrary date range rather than a calendar month.

Required fields

• type: month

Optional fields

• id — internal identifier.
• label — display label above the picker.
• param — parameter name to bind the value to. Defaults to id; if both are missing, defaults to the literal "month".
• default — month token (see below) or ISO string in YYYY-MM format. Defaults to the current month.
• year_min / year_max — explicit year bounds for the picker.
• year_window — symmetric relative bound: the picker spans that many years back and forward from the current year. year_window_past / year_window_future set the two sides independently and win over year_window. Default is ±5 years.
• month_picker — nested object accepting the same five year-bound keys (year_min, year_max, year_window, year_window_past, year_window_future), for authors who prefer them grouped; top-level keys win when both are set.

Scope note: the year-bound keys are honored on visualization-level month filters. On a dashboard-level month filter the schema currently accepts only id, type, label, param, and default — year-bound keys there fail validation.

Default tokens

Recognised tokens for the default field:

• {{current_month}} — the current calendar month in the workspace timezone. Aliases: {{this_month}}, {{month}}.
• {{previous_month}} — the calendar month before the current one (rolls back across year boundaries). Alias: {{last_month}}.

Anything else is treated as a literal YYYY-MM string (e.g. "2024-12"). Unrecognised tokens fall through to literal parsing and silently default to the current month if malformed.

How the value reaches the Malloy query

The picker emits a YYYY-MM string on submit. Looky sets the named parameter to that string. There is no automatic expansion to date_from / date_to — if the model needs a date range, derive it inside the query from the month string.

##! experimental.parameters

source: ec_revenue(
  p_month::string is "2024-01"
) is ecommerce.table('bigquery-public-data.thelook_ecommerce.order_items') extend {
  view: monthly_revenue is {
    where:
      format_datetime('%Y-%m', created_at) = p_month
    aggregate:
      revenue is sum(sale_price)
  }
}

(format_datetime is the BigQuery dialect function; on Postgres or MySQL derive the month inside a raw-SQL source with the dialect's own function — see the adapter note below.)

Adapter differences

The month value is a string, not a date / timestamp parameter, so the Postgres / MySQL caveat does not apply directly. If the model casts the month string to a date inside its parameter declaration, the same caveat applies for that derived parameter — see Source adapter differences.

Worked examples

Default to the current month, 5-year window centred on this year:

filters:
  - type: month
    id: month
    label: Month
    param: month
    default: "{{current_month}}"

Default to a literal historical month, with custom year window (3 years past, 1 year future):

filters:
  - type: month
    id: month
    label: Month
    default: "2024-12"
    year_window_past: 3
    year_window_future: 1

Frozen historical month (default fixed to a literal):

filters:
  - type: month
    label: Reporting month
    default: "2024-12"
    year_min: 2020
    year_max: 2024

Two month filters comparing periods:

filters:
  - type: month
    id: current_month
    label: Current
    param: current_month
    default: "{{current_month}}"
  - type: month
    id: comparison_month
    label: Compare to
    param: comparison_month
    default: "2024-11"