Filtro — month

Cuándo usar month

Usá 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.

Usá 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 (mirá 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, year_window_past, year_window_future — bounds relativos. Default a una ventana de 5 años centrada en el año actual.
month_picker — objeto anidado que te deja overridear la config de year-bound sin polucionar el top level.

Tokens default

Tokens reconocidos para el campo default:

— el calendar month actual en la timezone del usuario. Aliases: , .
— el calendar month antes del actual (rolla hacia atrás cruzando boundaries de año). Alias: .

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: revenue(
  p_month::string is "2024-01"
) is bigquery.table('...') extend {
  view: monthly_revenue is {
    where:
      format_datetime('%Y-%m', created_at) = p_month
    aggregate:
      revenue is sum(sale_price)
  }
}

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 — mirá 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: ""

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: ""
  - type: month
    id: comparison_month
    label: Compare to
    param: comparison_month
    default: "2024-11"

Errores comunes

El picker no muestra el año que querés. Seteá year_min / year_max explícitos, o expandí year_window_past / year_window_future.
El model espera una fecha, no un string. El picker de month emite YYYY-MM. O hacés que el parámetro del model sea un string y lo parseás en la query, o usás un filtro de fecha (date_range_preset con los presets this_month/last_month) en su lugar.
Dos filtros month bindean al mismo parámetro. Cada uno tiene que tener un param distinto (o id cuando param se omite), si no solo uno gana.
Se necesita selección multi-mes. No soportado por este filtro — usá date_range o date_range_preset.
Se necesita selección de quarter o semana. No implementado — derivá esos adentro del model desde un filtro de fecha, o pre-computá la periodicidad en la query subyacente.