Filtro — cutoff

Cuándo usar cutoff_date

Usa 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.

Usa date_range cuando el usuario necesita elegir los dos extremos libremente. Usa 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

id — identifier interno del filtro.
label — display label arriba del picker.
param — el nombre de parámetro bajo el cual también se manda la fecha de corte resuelta (default al id del filtro, y luego a cutoff_date). La ventana derivada siempre llega como date_from / date_to de todos modos.
default — token de fecha (mira abajo) o string ISO de fecha. Default a "{{today}}".
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. Mira 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 {{today}} 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 dashboards operativos en vivo — donde sí quieres incluir el día en curso — agrega include_current_day: true:

filters:
  - type: cutoff_date
    label: Cutoff
    default: "{{today}}"
    include_current_day: true

Con el flag prendido:

El picker permite seleccionar hoy como fecha máxima.
{{today}} 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 del workspace (ui.timezone en workspace.yml, cayendo al default de la instancia):

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

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: ec_orders(
  p_date_from::date is @2024-01-01,
  p_date_to::date   is @2024-12-31
) is ecommerce.table('bigquery-public-data.thelook_ecommerce.order_items') 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 — mira la comparación de adapters de source y Soporte de Malloy.

Ejemplos trabajados

Cutoff default es hoy:

filters:
  - type: cutoff_date
    label: Cutoff
    default: "{{today}}"

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

filters:
  - type: cutoff_date
    label: Closing date
    default: "{{end_of_month}}"

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

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

Filtro — cutoff_date