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), mira Models.

Para la referencia por tipo (cada propiedad chart.* que acepta cada viz type), mira 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 — mira la página por tipo.
chart — bloque de config tipado para los tipos basados en ECharts (bar, line, pie, scatter, heatmap, funnel, sankey). 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, report_matrix). Usa estos en vez de chart.
body — el cuerpo Markdown de una nota text (el único tipo donde query es opcional). Mira text.
pagination — para grid y report_matrix.
filters — lista de controles user-facing. Mira Filters.
format — patrones de format de número por campo; field name → pattern string. (En el tipo text, format es en cambio un escalar que nombra el format del body — markdown.)
emphasis — regla declarativa de highlight (por tipo soportado — mira las páginas por tipo).
execution — override del modo de ejecución. El engine lee execution.mode: default (implícito) o dry_run; dry_run se honra solo en BigQuery y se ignora con un warning en el resto.
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 — en bar, los measures siempre van en mapping.series[]:

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), mira 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, funnel, grid, report_matrix — más scatter, heatmap y sankey, que adicionalmente requieren chart.cross_filter_emit nombrando qué emite un click (label/x/series para scatter, x/y para heatmap, source/target para sankey).
No emiten pero consumen pills: kpi y text (sin 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, sankey); grid.cross_filter: false para grid; matrix.cross_filter: false para report_matrix.

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. El dry run también chequea que cada campo nombrado en mapping (y los otros slots de referencia a campos) exista en el schema de resultado de la query, y que cada key bajo format sea un slot de mapping o un campo del resultado. Con --strict, cada query se verifica adicionalmente contra el source vivo (estimación de costo en BigQuery, EXPLAIN en Postgres y MySQL).

La validación no verifica que el chart "se vea bien" — sizing, colisiones de labels, elecciones de color y issues de layout aparecen solo en tiempo de render. Abre la página de detalle de la visualization después del push para atraparlos.

looky validate
looky list visualizations