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. Elige 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 termina en el día elegido; granularity (day / month / quarter / year) decide dónde empieza el rango (default: primer día del mes de la fecha elegida). Usalo para reportes "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 — mira 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.

Dale a cada filtro un default para que la primera carga renderice con un valor que funciona. Para select, el default es el id de una de las options; los filtros de fecha aceptan un token ({{today}}, {{start_of_month}}, …) o una fecha ISO literal.

Una declaración a nivel dashboard se ve igual, en el top level del YAML del dashboard:

id: ec_business_overview
title: "What Is Happening In The Business?"
layout_mode: document
filters:
  - id: global_period
    type: cutoff_date
    granularity: year
    label: Period
    default: "{{today}}"
items:
  - visualization: ec_revenue_kpi

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. Overridea 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. Mira Soporte de Malloy.

Dónde viven los filtros

• En una sola visualization. Usa el filters: [] de la visualization cuando el control es local a ese chart — por ejemplo, un filtro de status por-grid.
• En un dashboard. Usa 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.

Dale a cada parámetro un solo dueño: o un filtro a nivel dashboard o un filtro por viz, no los dos. Cuando dos controles bindean el mismo parámetro, un solo valor gana en cada run.

Filtros vs cross-filtering

Los filtros son declarativos — tú decides 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, mezcla los dos: un set chico de filtros declarados arriba (period, region, channel) más el cross-filter implícito que responde a clicks. Mira 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). Mira Diferencias entre adapters de source y Models.