More Chart Types¶
Beyond the common charts, dbt Charts supports a fixed set of authored built-in
chart types. Arbitrary Vega-Lite mark, encoding, spec, config,
transform, params, and composition blocks are not part of the authored
dbt Charts schema.
Heatmap¶
Best for: Two-dimensional patterns, matrix data
source: examples_db
charts:
heatmap_example:
query:
sql: |
SELECT region, category, SUM(revenue) AS revenue
FROM ecommerce_orders
GROUP BY region, category
ORDER BY region, category
type: heatmap
title: Revenue by Region and Category
x: region
y: category
color: revenue
rows:
- heatmap_example
| Field | Required | Description |
|---|---|---|
x |
Yes | Column categories |
y |
Yes | Row categories |
color |
Yes | Value to color by |
Both axes default to the query's own row order. An authored sort: reorders
both the columns and the rows together: a heatmap has no way to sort one
axis without the other.
Conditional styling¶
style.conditional restyles a cell by the value in its own row. It maps a column name to a list of rules. Each rule is one condition (eq, ne, lt, lte, gt, gte, between, in, is_null, or default) plus the part of the chart style it applies:
type: heatmap x: day y: hour color: visits style: conditional: visits: - gte: 90 marks: rect: stroke: color: "#c62828" width: 3
A rule can set only what varies per cell:
| Field | Sets |
|---|---|
marks.rect.color |
The cell's fill |
marks.rect.opacity |
The fill opacity |
marks.rect.stroke.color, marks.rect.stroke.width |
The cell's outline |
axis_x.labels.font.color |
The category x-axis labels the rule matches (Conditional label colors) |
A stroke width needs a stroke color, from the rule or from marks.rect.stroke. A heatmap draws no cell text, so marks.text in a rule is refused, as is anything else that does not vary per cell.
- Every matching rule applies, and where two set the same field the later one wins, so list the more specific rule last.
- A
default: truerule must be last and applies only when no other rule matched. - The column must be in the query result. Rules on two columns cannot set the same field.
- A rule's color replaces the
color:channel's color for the matched cell only; the legend is unchanged. conditionalis authored on the chart's ownstyle; atstyle.charts.heatmapit is refused.
Histogram¶
Best for: Distribution of continuous values
source: examples_db
charts:
histogram_example:
query:
sql: |
SELECT * FROM ecommerce_orders
type: histogram
title: Revenue Distribution
x: revenue
rows:
- histogram_example
| Field | Required | Description |
|---|---|---|
x |
Yes | Continuous field to bin |
color |
No | Category grouping |
Histograms automatically bin the x-axis values.
Supported Built-In Types¶
Use type with one of the built-in names below. Unknown chart type names fail validation.
| Type | Description | Use Case |
|---|---|---|
bar |
Bar chart | Category comparisons |
histogram |
Auto-binned bar chart | Distributions |
line |
Line chart | Time series |
area |
Area chart | Stacked trends |
scatter |
Scatter plot | Scatter plots |
heatmap |
Color-coded matrix | Density, calendars |
pie |
Pie chart | Part-to-whole |
donut |
Pie with inner radius | Part-to-whole |
kpi |
Single-value indicator | Big numbers |
table |
Tabular display | Detailed values |
geoshape |
Geographic shapes | Maps |
map |
Filled region map | State/country metrics |
point_map |
Location markers | Plotting locations |
bubble_map |
Sized markers | Location + magnitude |
callout |
Annotated value | Highlighted measure |
spark_bar |
Inline mini bar chart | Compact trends |
Vega-Lite mark names such as boxplot, errorbar, errorband, tick, rect,
rule, text, trail, circle, square, image, and arc are not accepted
as authored chart type values.
Input Requirements¶
Quick reference for what each chart type needs:
| Type | Required | Optional |
|---|---|---|
bar |
x, y |
color, size |
line |
x, y |
color |
area |
x, y |
color |
scatter |
x, y |
color, size, shape |
heatmap |
x, y |
color (the measure; without it every cell is one color), pattern |
pie / donut |
theta |
color, style.inner_radius |
histogram |
x |
color |
kpi |
value |
label, glyph, support, style.variant, style.value.format |
table |
none | none |
geoshape / map |
Usually geo or geo_source |
lookup, value, color, projection |
point_map / bubble_map |
Usually latitude, longitude |
size, color, projection |
callout |
message |
title, style.tone |
spark_bar |
x, y |
style.max_bars |
The required channels are named together, or not at all: a chart naming none of them binds its query's columns by position (see Naming no channels).
Overlays and Mixed-Mark Charts¶
The cartesian chart families (bar, line, area, scatter) accept a layers: field
for mixed-mark or dual-axis compositions. layers: is not a chart type; it is a field
on a base chart.
charts: revenue_vs_target: type: bar x: month y: revenue query: monthly layers: - type: line y: target label: Target axis_y: position: right style: marks: line: stroke: width: 2
A layer on its own axis gets an independent scale; see Dual y-axis for why dbt Charts warns about it and what to use instead.
The base chart owns the x-axis, frame, title, legend, and sort order. Each layer
contributes its mark, its own y-axis side, and its own legend entry. See
Bar Charts, Line Graphs, and
Area Charts for full layers: examples.
Related¶
- Maps - Filled-region, point, and bubble maps
- Charts Overview - Field reference and styling
- Vega-Lite mark documentation - Underlying mark reference for the raw Vega-Lite types above