Filtro — month

Cuándo usar month

Usa month cuando el análisis está keyed a un solo mes — cierre mensual, billing mensual, reporting comparable-month-over-comparable-month. El usuario elige año + mes; el valor se manda como un string YYYY-MM al parámetro configurado.

Usa un filtro de fecha (cutoff_date, date_range, date_range_preset) en su lugar cuando el análisis abarca un date range arbitrario en vez de un calendar month.

Campos requeridos

• type: month

Campos opcionales

• id — identifier interno.
• label — display label arriba del picker.
• param — nombre de parámetro al que bindear el valor. Default a id; si los dos faltan, default al literal "month".
• default — token de mes (mira abajo) o string ISO en formato YYYY-MM. Default al mes actual.
• year_min / year_max — bounds de año explícitos para el picker.
• year_window — bound relativo simétrico: el picker abarca esa cantidad de años hacia atrás y hacia adelante desde el año actual. year_window_past / year_window_future setean los dos lados independientemente y ganan sobre year_window. El default es ±5 años.
• month_picker — objeto anidado que acepta las mismas cinco keys de year-bound (year_min, year_max, year_window, year_window_past, year_window_future), para autores que las prefieren agrupadas; las keys top-level ganan cuando los dos están seteados.

Nota de scope: las keys de year-bound se honran en filtros month a nivel visualization. En un filtro month a nivel dashboard el schema actualmente acepta solo id, type, label, param y default — las keys de year-bound ahí fallan la validación.

Tokens default

Tokens reconocidos para el campo default:

• {{current_month}} — el calendar month actual en la timezone del workspace. Aliases: {{this_month}}, {{month}}.
• {{previous_month}} — el calendar month antes del actual (rolla hacia atrás cruzando boundaries de año). Alias: {{last_month}}.

Cualquier otra cosa se trata como un string literal YYYY-MM (ej. "2024-12"). Tokens no reconocidos caen a parsing literal y silenciosamente defaultean al mes actual si están malformados.

Cómo llega el valor a la query Malloy

El picker emite un string YYYY-MM al submit. Looky setea el parámetro con nombre a ese string. No hay expansión automática a date_from / date_to — si el model necesita un date range, derivalo adentro de la query desde el string del mes.

##! 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 es la función del dialecto de BigQuery; en Postgres o MySQL deriva el mes dentro de un source de SQL crudo con la función propia del dialecto — mira la nota de adapters abajo.)

Diferencias entre adapters

El valor de month es un string, no un parámetro de date / timestamp, así que la caveat de Postgres / MySQL no aplica directo. Si el model castea el string del mes a una fecha dentro de la declaración de parámetro, aplica la misma caveat para ese parámetro derivado — mira Diferencias entre adapters de source.

Ejemplos trabajados

Default al mes actual, ventana de 5 años centrada en este año:

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

Default a un mes histórico literal, con ventana de año custom (3 años pasados, 1 año futuro):

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

Mes histórico congelado (default fijo a literal):

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

Dos filtros month comparando períodos:

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"