malloy-charts

Files (1)

• SKILL.md

SKILL.md (first lines)

<!--
Copyright (c) Credible Data Inc.
SPDX-License-Identifier: MIT
-->

# Chart Selection for Malloy

> Malloy uses Vega-Lite under the hood. `#` tags control visualization. Call `search_malloy_docs` with topic "rendering" for the full tag reference (or see https://docs.malloydata.dev/documentation/visualizations/overview).

> **This file is about the Malloy renderer's `#` tags.** It applies when the view itself is rendered - a tile or cell in a report (either layout), an explore result. It does **not** apply to an app that draws its own charts with a vendored chart library: there the tag vocabulary is irrelevant and the full form vocabulary is available, so the approximations below (a funnel as a bar chart, a treemap as a nested table) are the wrong advice. Design to whichever vocabulary the surface actually uses.

> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.

## Decision Tree: Which Chart?

| Data Shape | Default Choice |
|-----------|---------------|
| Aggregates only (no group_by) | `# big_value` |
| 1 time column + 1 measure | `# line_chart` |
| 1 category + 1 measure | `# bar_chart` |
| 2 numeric columns | `# scatter_chart` |
| Geographic (US states) + 1 measure | `# shape_map` |
| Route data (lat/lon pairs) | `# segment_map` |
| Multiple perspectives | `# dashboard` with `nest:` |
| Nested query to pivot | `# pivot` |
| Filtered aggregates side-by-side | `# flatten` |
| Detailed rows | Default table (no annotation) |

| Goal | Renderer |
|------|---------|
| Compare categories | `# bar_chart` (sort by value, limit ~15) |
| Show composition | `# bar_chart.stack` |
| Trend over time | `# line_chart` |
| Highlight KPIs | `# big_value` with `# label` |
| Correlation | `# scatter_chart` |
| Compare dimensions | `# dashboard` (nest chart views) |
| Before/after | `# transpose` or `# pivot` |
| Multiple metrics per category | Default table, `# flatten`, or `y=['a','b']` |

**Constraints:**
- ONE aggregate per chart view (charts render only the first; use `y=['a','b']` for multi-measure)
- No fixed scale on measure definitions: use `# currency` not `# currency=usd0m`. The same measure renders at many granularities, and `usd0m` turns $500 into `$0.0M`. Add a scale only in a view, after confirming the value range with a query.
- One tag per line, each directly above the field it styles. Two `#` tags on one line do not work.
- Alias joined fields in `group_by` before `order_by`
- Define measures in source, not in views


## Chart Types

### `# bar_chart`

**Data shape:** `group_by` = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.

```malloy
# bar_chart
view: by_carrier is { group_by: carrier, aggregate: flight_count, order_by: flight_count desc, limit: 10 }

# bar_chart.stack
view: by_region is { group_by: category, region, aggregate: revenue }

# bar_chart { y=['revenue','cost'] }
view: rev_vs_cost is { group_by: category, aggregate: revenue, cost }
```

**Key properties:** `.stack`, `.size` (spark/xs/sm/md/lg/xl/2xl), `.x`, `.x.limit`, `.y` (supports `y=['a','b']`), `.series`, `.series.limit` (default 20), `.title`, `.subtitle`, `.x.independent`, `.y.independent`

**Field role tags:** `# x`, `# y`, `# series` on individual fields to assign roles explicitly.

### `# line_chart`

**Data shape:** `group_by` (temporal/numeric) = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.

```malloy
# line_chart
view: trend is { group_by: order_month, aggregate: revenue, order_by: order_month }

# line_chart { size=spark }
view: mini_trend is { group_by: order_month, aggregate: revenue, order_by: order_month }
```

**Key properties:** `.zero_baseline`, `.interpolate` (e.g., `step`), `.size`, `.y` (supports `y=['a','b']`), `.series.limit` (default 12), `.title`, `.subtitle`

### `# scatter_chart`

**Data shape:** Fields by position: x, y, color, size (bubble), shape.

```malloy
# scatter_chart
view: correlation is { group_by: customer_id, aggregate: avg_price, total_quantity }
```

### `# shape_map`

Choropleth. US states only. Fields: state name, value.

```malloy
# shape_map
view: by_state is { group_by: state, aggregate: revenue }
```

### `# segment_map`

Route map. US only. Fields: start_lat, start_lon, end_lat, end_lon, color.


## Layout Types

### `# big_value`

KPI cards. Aggregates only, no `group_by`.

```malloy
# big_value
view: summary is {
  aggregate:
    # label="Revenue"
    # currency
    revenue
    # label="Orders"
    # number=auto

From malloydata/publisher, MIT.

More from malloydata/publisher