Visualizations

Para qué sirve un YAML de visualization

Un archivo de visualization ata una query de Malloy a un chart o una tabla. Cada transformación pertenece a la query del model; el YAML de visualization es solo presentación — chart type, qué campos van dónde, formatting, énfasis opcional. Para saber cómo formar esa capa de Malloy (dimensions, measures, views, archivos modulares), mirá Models.

Para la referencia por tipo (cada propiedad chart.* que acepta cada viz type), mirá Tipos de visualization y la página de cada tipo.

Campos top-level requeridos

id — identifier único en el workspace. Estable en el tiempo: los dashboards lo referencian, así que renombrarlo rompe dashboards.
title — título legible que se muestra en el dashboard.
type — discriminador del viz type. Tiene que ser uno de los tipos soportados listados en el índice de viz-types; cualquier otro se rechaza en tiempo de validación.
query — referencia a query de Malloy, exactamente en formato path/to/file.malloy::query_name. El path es desde el root del workspace; las dos mitades tienen que existir o la validación falla.

Otros campos top-level

mapping — asignaciones de rol de campo. El shape varía por viz type — mirá la página por tipo.
chart — bloque de config tipado para los tipos basados en ECharts (bar, line, pie, scatter, heatmap, funnel). Superficie cerrada: solo las keys listadas en la referencia por tipo son aceptadas.
kpi, grid, matrix — bloques específicos del tipo para los tipos basados en DOM (kpi, grid/table, report_matrix). Usá estos en vez de chart.
pagination — para grid y report_matrix.
filters — lista de controles user-facing. Mirá Filters.
format — patrones de format de número/fecha por campo; field name → pattern string.
emphasis — regla declarativa de highlight (por tipo soportado — mirá las páginas por tipo).
execution — hints de ejecución de query (timeout, concurrency, override de cache). Shape permisivo hoy.
tags — labels free-form para búsqueda.
published — boolean. Solo visualizations con true aparecen en dashboards.

El formato de query reference

Cada visualization apunta a una query de Malloy con este formato exacto:

query: "models/ec_revenue.malloy::by_category"

La parte antes de :: es el path al archivo .malloy desde el root del workspace. La parte después de :: es el nombre de la view o query definida dentro de ese archivo. Las dos tienen que matchear exacto.

La validación local (looky validate) chequea que el archivo existe y que la referencia usa el separador ::. La validación server-side adicionalmente compila el model y hace dry-run de la query; si el nombre de la view no existe, o el model no compila, te queda un error claro antes del push.

Ejemplos trabajados

KPI mínimo:

id: ec_revenue_kpi
title: Revenue
query: "models/ec_revenue.malloy::kpi"
type: kpi
mapping:
  value: revenue
  delta: revenue_delta_pct
format:
  revenue: "$#,##0a"
  revenue_delta_pct: "#,##0.00%"
published: true

Bar con una serie — notá mapping.series[] (el legacy mapping.y ya no se acepta en bar):

id: ec_revenue_by_category_bar
title: Revenue by Category
query: "models/ec_revenue.malloy::by_category"
type: bar
mapping:
  x: category
  series:
    - field: revenue
      label: Revenue
chart:
  show_value_labels: true
  value_label:
    position: top
format:
  revenue: "$#,##0.00"
published: true

Line con doble eje:

id: ec_revenue_over_time_line
title: Revenue Over Time
query: "models/ec_revenue.malloy::over_time"
type: line
mapping:
  x: order_month
  y: revenue
  y2: order_count
  series_label: Revenue
  series_label_2: Orders
format:
  revenue: "$#,##0"
  order_count: "#,##0"
published: true

Para cada otro shape (grouped bars, percent-stacked, donut pie, scatter, heatmap, funnel, grid con paginación, report_matrix con totales), mirá las páginas por tipo bajo Tipos de visualization.

Cross-filtering de un vistazo

Dentro de un dashboard, clickear un chart puede agregar un "pill" que estrecha cada otra viz de la página. Comportamiento de emit por tipo:

Emiten clicks: bar, line, pie, scatter, funnel, grid, report_matrix, heatmap (este último requiere chart.cross_filter_emit seteado a "x" o "y").
No emiten pero consumen pills: kpi (no tiene target categórico de click por estructura).
Opt-out por viz: chart.cross_filter: false para vizs basadas en ECharts (bar, line, pie, scatter, heatmap, funnel); grid.cross_filter: false para grid; matrix.cross_filter: false para report_matrix. KPI no emite por estructura.

Mecanismo completo en Cross-filtering.

Qué chequea la validación de verdad (y qué no)

La Validación es de dos pasadas — local y después server-side. Por visualization, los chequeos son:

Local: el YAML parsea; id, title, type, query están presentes y no vacíos; query usa el separador ::; el archivo de model existe; el id es único en todo el workspace; el bloque chart es schema-válido (cada propiedad se reconoce, los valores están en el rango permitido — error VZ020).
Server-side: el model Malloy subyacente compila, los sources son alcanzables, y la query hace dry-run contra el engine de runtime (gratis en BigQuery, EXPLAIN-only en Postgres en --strict).

La validación no verifica que cada campo en mapping exista en el resultado de la query, ni que cada campo en format aparezca en mapping, ni que el chart "se vea bien". Esos issues aparecen solo en tiempo de render. Abrí la página de detalle de la visualization después del push para atraparlos.

looky validate
looky list visualizations