Filtro — cutoff

Cuándo usar cutoff_date

Usá cutoff_date cuando el análisis es "todo desde el comienzo del mes hasta un día elegido" — revenue month-to-date, reportes de cierre mensual, snapshots "as-of". El usuario elige una sola fecha; Looky manda automáticamente tanto date_from (el primer día de ese mes) como date_to (la fecha elegida) como parámetros.

Usá date_range cuando el usuario necesita elegir los dos extremos libremente. Usá date_range_preset cuando la elección es entre presets con nombre como "last 30 days" o "this quarter".

Campos requeridos

type: cutoff_date

Campos opcionales

label — display label arriba del picker.
default — token de fecha (mirá abajo) o string ISO de fecha. Default a "".
granularity — controla cómo se deriva date_from desde la fecha elegida. Uno de day, month (default), quarter, year. Con day, date_from iguala a la fecha elegida (ventana de un día). Con month, el primer día del mes de la fecha elegida. Con quarter, el primer día del calendar quarter de la fecha elegida (Ene, Abr, Jul u Oct). Con year, 1 de enero del año de la fecha elegida. Honrado tanto a nivel dashboard como visualization.
include_current_day — boolean. Default false. Mirá Máximo seleccionable.

Máximo seleccionable — hoy o ayer

Por default, el filtro cutoff_date capa la fecha máxima en hoy − 1 día. El picker no permite seleccionar hoy, el token resuelve a hoy pero se baja a ayer, y los date_to enviados a la query siempre terminan en ayer. Esa es la convención histórica de reportes "as-of cierre del día anterior": los datos del día en curso suelen estar incompletos hasta el cierre del día, así que el reporte se ancla al último día cerrado.

Para casos operativos en vivo — donde sí querés ver datos del día en curso — agregá include_current_day: true:

filters:
  - type: cutoff_date
    label: Fecha de corte
    default: ""
    include_current_day: true

Con el flag prendido:

El picker permite seleccionar hoy como fecha máxima.
resuelve a hoy y no se clampa.
Los date_to enviados a la query son inclusivos del día en curso.

El flag es opt-in (default false) para preservar back-compat con dashboards de reporte diario (PDFs, cierres de período) cuya semántica espera "hasta ayer cerrado".

Cuándo prenderlo: dashboards operativos en vivo, KPIs de "lo que llevo hasta este instante", facturación en curso, monitoreo de avance. Cuándo dejarlo apagado (default): reportes que se exportan a PDF y se envían como cierre de día, snapshots históricos, reportes que requieren consolidación post-cierre.

El flag se declara independientemente en cada filter — en la visualization (si se abre suelta) y en el dashboard (si tiene un filter global que propaga vía param:). Si la viz vive dentro de un dashboard con filter global, el flag del dashboard es suficiente; el valor resuelto llega a la viz vía param.

Tokens de fecha para defaults

Estos tokens resuelven contra la timezone actual del usuario en page load:

Cualquier cosa que no esté en esta lista se trata como un string ISO de fecha literal (ej. "2024-12-31").

Cómo llega el valor a la query Malloy

La fecha elegida setea dos parámetros en cada query a la que aplica el filtro:

date_from — derivado de la fecha elegida según granularity (default al primer día de su mes).
date_to — la fecha elegida misma.

Tu model de Malloy declara esos dos parámetros y los usa en cláusulas where::

##! experimental.parameters

source: orders(
  p_date_from::date is @2024-01-01,
  p_date_to::date   is @2024-12-31
) is bigquery.table('...') extend {
  view: revenue_mtd is {
    where:
      created_at::date >= p_date_from
      and created_at::date <= p_date_to
    aggregate:
      revenue is sum(sale_price)
  }
}

Diferencias entre adapters

Tanto date_from como date_to son parámetros de date / timestamp. En BigQuery bindean nativo. En Postgres y MySQL el model tiene que usar el patrón de placeholder @param en el SQL subyacente — mirá la comparación de adapters de source y Soporte de Malloy.

Ejemplos trabajados

Cutoff default es hoy:

filters:
  - type: cutoff_date
    label: Cutoff
    default: ""

Cutoff default es fin del mes pasado (para reportes de cierre mensual):

filters:
  - type: cutoff_date
    label: Closing date
    default: ""

Cutoff default es una fecha literal (para un snapshot histórico fijo):

filters:
  - type: cutoff_date
    label: As of
    default: "2024-12-31"

Errores comunes

La query necesita otro shape de rango. cutoff_date es opinionado: date_from hace snap al comienzo de la ventana de granularity de la fecha elegida (day, month, quarter, year). Si necesitás que el usuario elija el lower bound libremente, usá date_range.
El model Malloy espera nombres de parámetro distintos. cutoff_date siempre emite date_from / date_to. Adaptá los nombres de parámetro del model en consecuencia, o usá date_range_preset que soporta bindings custom.
La query falla en Postgres o MySQL con un error de date-binding. Agregá el patrón de placeholder @param en el SQL del model — mirá la comparación de adapters de source.
El token default no se reconoce. Solo los tokens listados arriba son válidos. Cualquier otra cosa se trata como un string de fecha literal y silenciosamente no hace nada útil si está malformado.
Múltiples filtros cutoff_date en una viz. Solo un cutoff aplica. Usá otro tipo de filtro (o dos pares de parámetros separados) si necesitás múltiples ventanas temporales.
"El reporte muestra hasta ayer aunque puse ". Es el comportamiento por default — el cutoff se clampa a hoy − 1. Si querés incluir el día en curso, agregá include_current_day: true al filter. Mirá Máximo seleccionable.
El flag include_current_day está en la viz pero el dashboard sigue mostrando ayer. Cuando la viz vive dentro de un dashboard con filter global (param: cutoff_date), es el flag del filter del dashboard el que manda — el dashboard resuelve el valor y lo propaga a la viz vía param. Prendé el flag en el filter del dashboard, no solo en la viz.

Filtro — cutoff_date