Filters

Qué es un filtro en Looky

Un filtro es un control user-facing en una visualization o un dashboard. El usuario elige un valor; Looky lo manda a la query Malloy subyacente como un parámetro con nombre. Los filtros viven en el YAML de la visualization (o del dashboard) bajo filters: [], una entry por control.

Filtros y cross-filtering son mecanismos distintos. Los filtros son controles declarativos con los que el usuario interactúa explícitamente. Cross-filtering es automático — clickear un chart dentro de un dashboard agrega un "pill" que se convierte en un parámetro sin ningún YAML.

Elegir un tipo de filtro

Hay cinco tipos de filtro soportados. Elegí el que su UI matchee el input que el usuario está eligiendo.

• select — picker dropdown. La lista de opciones se declara en YAML o se resuelve dinámicamente corriendo una query Malloy en page load.
• cutoff_date — una sola fecha que se expande automáticamente a un rango date_from / date_to que va desde el primer día de ese mes hasta el día elegido. Usalo para reportes "month-to-date as of".
• date_range — picker abierto de from / to date. Usalo cuando el usuario necesita elegir los dos extremos libremente.
• date_range_preset — date range elegido desde presets con nombre (last_30_days, this_month, last_month, this_year, etc.). El default para la mayoría de los dashboards operacionales.
• month — picker de año + mes con bounds configurables. Usalo cuando el análisis está keyed a un solo mes (cierre mensual, billing mensual).

Otros tipos de filtro no están soportados.

Anatomía de una declaración de filtro

Cada entry de filtro es un objeto con al menos un type. Las otras keys dependen del tipo — mirá la página de referencia de cada tipo para la lista completa.

id: orders_grid
type: grid
query: "models/ec_fulfillment.malloy::detail"
filters:
  - type: select
    id: status
    label: Status
    param: status
    options_query: "models/ec_fulfillment.malloy::status_options"
    default: all
  - type: date_range_preset
    id: period
    label: Period
    default:
      preset: last_30_days

El orden en el array es el orden en el que los controles renderizan en la UI.

Cómo llega el valor del filtro a la query de Malloy

El valor elegido en el control de filtro se manda a la query como un parámetro con nombre. El model declara el parámetro y lo usa adentro de la query.

• Para select, cutoff_date y month, el nombre del parámetro es lo que pongas en el campo param del filtro (o, cuando se omite, el id del filtro).
• Para date_range y date_range_preset, los parámetros son date_from y date_to por default. Overrideá los nombres a través del bloque bindings: { date_from, date_to } del filtro cuando el model espera nombres de parámetro distintos.

Convención de naming: los parámetros cuyo nombre Malloy empieza con p_ tienen el prefix strippeado para el nombre externo. Un parámetro de model declarado como p_start_date se setea mandando start_date. Mirá Soporte de Malloy.

Dónde viven los filtros

• En una sola visualization. Usá el filters: [] de la visualization cuando el control es local a ese chart — por ejemplo, un filtro de status por-grid.
• En un dashboard. Usá el filters: [] del dashboard cuando el control debería estrechar cada viz de la página — por ejemplo, un filtro global "Period" arriba de un dashboard ejecutivo.

Un filtro a nivel dashboard aplica a cada viz que el dashboard contiene, pero solo si el model subyacente de cada viz declara el parámetro matcheante.

Filtros vs cross-filtering

Los filtros son declarativos — vos decidís en YAML qué controles ve el usuario. El cross-filtering es interactivo — el usuario clickea un chart y el dashboard agrega el filtro implícito como un pill. Los dos terminan en el mismo lugar: un parámetro de Malloy en el próximo run. La única diferencia es quién inicia el filtro.

Para la mayoría de los dashboards, mezclá los dos: un set chico de filtros declarados arriba (period, region, channel) más el cross-filter implícito que responde a clicks. Mirá Cross-filtering.

Diferencias entre adapters

La UI de filtro se comporta igual sobre cualquier source. Las diferencias aparecen cuando el valor del filtro se bindea al parámetro subyacente — más importante para filtros de date / timestamp contra models con backing de Postgres o MySQL, que usan el patrón de placeholder @param en SQL crudo (cada @param declarado en la signature del source, valor sustituido en el string SQL en tiempo de run). Mirá Diferencias entre adapters de source y Models.

Errores comunes

• El filtro aparece pero no estrecha los datos. El model tiene que declarar un parámetro con el nombre matcheante (después de strippear el prefix p_) dentro de los paréntesis del source. Chequeá la signature del source en el archivo .malloy.
• Dos filtros se bindean al mismo parámetro. Solo uno gana. Elegí una sola fuente de verdad por parámetro — o un filtro a nivel dashboard o un filtro por-viz, no los dos.
• Validate falla con unbound_param. El model usa un placeholder @param en SQL crudo que no está declarado en la signature del source. El error nombra el parámetro faltante — agregalo a los paréntesis del source.
• Un filtro de fecha en un model Postgres o MySQL falla. Usá el patrón de placeholder @param en SQL crudo en el SQL del model con una declaración matcheante en la signature del source — mirá Diferencias entre adapters de source.
• El valor default no carga. Para select, el default tiene que matchear el id de una de las opciones. Para filtros de fecha, usá los tokens soportados (, , etc.) o un string ISO literal.
• El filtro espera un valor que el usuario no provee. O seteás un default razonable en el filtro, o declarás un default en la signature del source así la query igual corre cuando el parámetro falta.