Tipos de visualization

Un tipo para un propósito

Cada tipo de visualization responde una clase específica de pregunta. Elegir el tipo correcto no es sobre estética — es sobre hacer la respuesta legible a primera vista. Cada tipo tiene su propia página de referencia profunda abajo; cada página enumera exactamente qué campos mapping.* y chart.* lee el renderer, el comportamiento de cross-filter, ejemplos trabajados y notas de diseño.

Todas las visualizations comparten los mismos campos top-level (id, title, query, type, filters, format, published). La configuración por tipo vive en mapping más exactamente uno de: un bloque chart (para tipos basados en ECharts), un bloque type-específico (kpi, grid, matrix) para los tipos basados en DOM, o un body Markdown para la nota text. La nota text es además el único tipo donde query es opcional — una nota sin query es prosa pura.

Tipos soportados

Once tipos se aceptan en el campo type: — exactamente estos tokens, nada más. Nota que report_matrix se escribe con underscore, y no existe un tipo table ni number (una tabla de datos es grid; una cifra única es kpi).

• kpi — métrica única con delta y comparación opcionales.
• bar — comparación categórica; soporta stacking, dual-axis, orientación horizontal.
• line — series de tiempo; soporta dual axis y multi-series.
• pie — composición part-of-whole; soporta variantes donut y rose.
• scatter — correlación de dos measures; un punto por fila.
• heatmap — grid de intensidad bidimensional con scale de color explícita.
• funnel — stages de conversión o pipeline con drop-off.
• sankey — diagrama de flujo / atribución; una fila = un link (source → target).
• grid — tabla de datos row-level; soporta paginación, columnas congeladas, celdas compuestas.
• report_matrix — reporte jerárquico con filas agrupadas, totales y PDF export.
• text — una nota Markdown: encabezados, prosa e instrucciones colocadas entre los charts. Opcionalmente entreteje un valor en vivo desde una query de una sola fila en una oración.

Cualquier otra cosa pasada como type: no está soportada y se rechaza en tiempo de validación.

El bloque chart es tipado y cerrado

Para tipos basados en ECharts (bar, line, pie, scatter, heatmap, funnel, sankey) el bloque chart es una superficie chica y tipada. Tres categorías de propiedades viven adentro:

• Shortcuts de Looky — keys únicas que colapsan múltiples decisiones coordinadas en una sola decisión (ej. chart.stack: percent, chart.variant: donut, chart.show_value_labels).
• Campos pass-through — escalares o arrays espejados a una opción subyacente específica (ej. chart.center, chart.symbol_size, chart.gap).
• Bloques pass-through — objetos anidados con un set curado snake_case de propiedades (ej. chart.legend, chart.tooltip, chart.x_axis, chart.y_axis, chart.value_label, chart.label, chart.visual_map).

Cualquier propiedad no listada en la página de referencia por tipo se rechaza en tiempo de validación. No hay escape hatch para opciones raw de la chart library.

Los tipos basados en DOM usan su propio bloque

kpi, grid, report_matrix y text no están construidos sobre una chart library, así que no tienen un bloque chart en absoluto. kpi, grid y report_matrix usan un bloque top-level type-específico — kpi, grid, matrix — más bloques auxiliares (pagination para grid y report_matrix, comparison para kpi).

La nota text en cambio lleva un body Markdown. Una nota estática es prosa pura y no necesita query. Para entretejer un valor en vivo en una oración, agrega una query de una sola fila y un mapping de nombres de token a fields del resultado, y referencialos en el body como {{ token }} o {{ token | "$#,##0" }} — cada valor se escapa y opcionalmente se formatea como número. Los links en el body aceptan solo URLs http, https y relativas.

Dónde buscar cada tópico

• Qué campos acepta cada viz type — la página de referencia por tipo arriba.
• Cómo se cablean los filtros — Filters.
• Comportamiento de cross-filter — Cross-filtering.
• Qué sintaxis de Malloy entiende el engine — Soporte de Malloy.
• Cómo los dashboards componen visualizations — Dashboards.
• Divergencias de adapter — Diferencias entre adapters de source.

Referencia de format strings (compartida por cada tipo)

El formato de número es field-keyed en todos los tipos de viz. Los patterns por field ganan sobre patterns de slot; los patterns de slot ganan sobre el pattern root.

Un pattern se lee de izquierda a derecha como: + opcional (mostrar siempre el signo) → currency opcional ($ o un código de 3 letras como EUR) → el núcleo de dígitos → % opcional → a (compacto) o b (bytes) opcional.

El núcleo de dígitos usa 0 para un dígito obligatorio y # para uno opcional. Los separadores son literales — la puntuación propia del pattern decide la puntuación del output: el último . o , seguido de uno o dos placeholders de dígito es el separador decimal; cualquier otro separador en la parte entera se vuelve el separador de miles. Eso significa que ambas convenciones funcionan, y significan cosas distintas:

Cada ejemplo en estos docs usa la convención estilo US (#,##0.00); elige una convención por workspace y mantente consistente — mezclar #0,00 (coma decimal) en un workspace de patterns #,##0 produce números que se leen mal para la mitad de tu audiencia.

Si no hay format pattern seteado para un field, la plataforma cae a un format decimal default con dos dígitos de fracción.