Point Charts¶
Point charts encode values primarily through the position of points, often on one or two common scales; this family includes dot plots, lollipop charts, scatterplots, beeswarm, and strip plots. They are especially useful when precision, comparison, distribution, or relationships matter, with dot plots and lollipops excelling at ranked comparisons and scatterplots excelling at showing association between two variables.
dbt Charts point charts currently map most directly to scatterplots and dot-plot-style charts. The canonical type is type: scatter: it uses Vega-Lite point marks under the hood and supports the familiar point-chart channels such as color, size, and shape.
A chart's control surface is the full set of authored properties available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus a typed style object.
This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the YAML Schema Reference.
Minimum Required for a Point Chart¶
These are the minimum fields required to render a basic point chart in dbt Charts. In practice, that minimum usually means a scatterplot, so type: scatter is the most natural starting point.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
query |
data.values |
Query name or query reference | Supplies the dataset. |
type: scatter |
mark.type: "point" |
Literal scatter |
Recommended starting point for scatterplots and dot-plot-style point charts. |
x |
encoding.x.field |
Field name | First position field. |
y |
encoding.y.field |
Field name | Second position field. |
Minimum Example¶
queries:
campaign_efficiency:
columns: [ad_spend, pipeline_value]
values:
- [18, 140]
- [22, 165]
- [26, 182]
- [31, 205]
- [34, 214]
- [39, 246]
charts:
spend_vs_pipeline:
query: campaign_efficiency
type: scatter
title: Ad Spend vs Pipeline Value
x: ad_spend
y: pipeline_value
rows:
- spend_vs_pipeline
Top-Level Chart Fields¶
These are the top-level chart properties you set directly on a point chart before you get into nested properties under style.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
query |
data.values |
Query name or query reference | Query results become the plotted dataset. |
type: scatter |
mark.type: "point" |
Literal scatter |
Canonical point-chart type. |
x |
encoding.x.field |
Field name | First position field. Often quantitative, but categorical x fields also support dot-plot-style charts. |
y |
encoding.y.field |
Field name | Second position field. Often quantitative in scatterplots and categorical in dot plots. |
title |
title.text |
String | Chart title. |
notes |
metadata | String | AI search/context metadata. Never rendered. |
color |
encoding.color.field |
Field name | Category or grouping field. |
size |
encoding.size.field |
Field name | Quantitative field mapped to point size. |
shape |
encoding.shape.field |
Field name | Category field mapped to symbol shape. |
x_label |
encoding.x.title |
String | Custom x-axis title. |
y_label |
encoding.y.title |
String | Custom y-axis title. |
field_labels |
legend, tooltip and axis titles | Map of column to text | Display text for a column, painted as written. See Field Labels. |
tooltip |
hover card rows | List of column names or {column, label, format} |
Query columns to add to the hover card. See Add columns to the tooltip. |
format |
quantitative y-axis format | Format string | Numeric formatting for the quantitative y axis. Use style.axis_x when you need x-axis formatting too. |
sort |
categorical axis sort | Sort object | Most useful for dot plots and other ordered categorical comparisons. |
Size and Category Grouping¶
This example shows the most common top-level point-chart additions after x and y: color for grouping and size for magnitude.
queries:
segment_performance:
columns: [avg_deal_size, win_rate, segment, open_pipeline]
values:
- [18000, 0.22, "SMB", 45]
- [24000, 0.26, "SMB", 58]
- [52000, 0.31, "Mid-Market", 72]
- [61000, 0.34, "Mid-Market", 86]
- [120000, 0.41, "Enterprise", 108]
- [138000, 0.44, "Enterprise", 124]
- [195000, 0.37, "Strategic", 140]
- [215000, 0.40, "Strategic", 156]
charts:
segment_scatter:
query: segment_performance
type: scatter
title: Deal Size vs Win Rate by Segment
x: avg_deal_size
y: win_rate
color: segment
size: open_pipeline
x_label: Average Deal Size
y_label: Win Rate
style:
axis_x:
labels:
format: currency_whole
axis_y:
labels:
format: percent_whole
rows:
- segment_scatter
Dot Plot¶
This example uses the same point-chart family to create a dot plot, where the y-axis is categorical and the x-axis carries the quantitative comparison.
queries:
response_times:
columns: [team, median_response_hours]
values:
- ["Onboarding", 1.8]
- ["Support", 2.4]
- ["Success", 3.1]
- ["Renewals", 4.0]
- ["Escalations", 5.3]
charts:
team_response_dots:
query: response_times
type: scatter
title: Median Response Time by Team
x: median_response_hours
y: team
x_label: Hours
y_label: Team
sort:
by: median_response_hours
order: desc
style:
axis_x:
labels:
format: ".1f"
rows:
- team_response_dots
Style Fields¶
Use style for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and gridlines.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
style.legend.visible |
encoding.color.legend |
true or false |
Typed legend control. false hides the legend. |
style.axis.grid.visible |
axis grid visibility | true or false |
false hides gridlines. Use style.axis.grid.visible: false (nested under grid:). |
style.background |
chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered SVG. |
style.size.range |
encoding.size.scale.range |
[low, high] in px², 0 <= low < high |
The mark area of the smallest and largest size: value. Needs a size: field. |
style.size.type |
encoding.size.scale.type |
linear, sqrt, log |
How a size: value maps onto the range. Default linear. |
Legend and Gridlines¶
This example keeps the same basic scatter structure while showing the small style surface for point charts.
queries:
experiment_results:
columns: [confidence, lift, cohort]
values:
- [0.62, 0.07, "Baseline"]
- [0.68, 0.10, "Baseline"]
- [0.73, 0.12, "Baseline"]
- [0.66, 0.14, "Guided"]
- [0.71, 0.17, "Guided"]
- [0.77, 0.19, "Guided"]
charts:
experiment_scatter:
query: experiment_results
type: scatter
title: Confidence vs Lift
x: confidence
y: lift
color: cohort
style:
legend:
visible: false
axis:
grid:
visible: false
axis_x:
labels:
format: percent_whole
axis_y:
labels:
format: percent_whole
rows:
- experiment_scatter
Axis and Scale Style¶
Use style for axis and scale properties that shape how a point chart is framed and read.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
style.axis_x |
config.axisX / encoding.x.axis |
axis object | Per-axis styling (labels, ticks, grid, title, scale). |
style.axis_y |
config.axisY / encoding.y.axis |
axis object | Per-axis styling. |
style.axis_x.scale |
config.axisX.scale |
scale object | X-axis scale config (domain, nice, clamp). |
style.axis_y.scale |
config.axisY.scale |
scale object | Y-axis scale config (zero, domain, nice, clamp). |
Axis Formatting and Scale Bounds¶
This example shows the most common style work on point charts: formatting axes and trimming the visible scale range to the comparison that matters.
queries:
product_health:
columns: [activation_rate, retention_rate]
values:
- [0.52, 0.67]
- [0.58, 0.71]
- [0.63, 0.74]
- [0.69, 0.78]
- [0.74, 0.83]
- [0.81, 0.88]
charts:
health_scatter:
query: product_health
type: scatter
title: Activation Rate vs Retention Rate
x: activation_rate
y: retention_rate
style:
axis_x:
labels:
format: percent_whole
scale:
continuous:
zero: false
axis_y:
labels:
format: percent_whole
scale:
continuous:
zero: false
rows:
- health_scatter
Value Labels¶
Show the numeric value beside each point on a scatter chart by enabling style.marks.point.labels.visible. style.marks.point.color recolors the dots of a single-series scatter; with a color channel the series palette colors them.
queries: product_health: columns: [activation_rate, retention_rate] values: - [0.52, 0.67] - [0.58, 0.71] charts: health_scatter: query: product_health type: scatter x: activation_rate y: retention_rate style: marks: point: color: "#c2410c" labels: visible: true format: percent_whole rows: - health_scatter
Position values:
| Value | Placement |
|---|---|
top |
Above the point, default |
bottom |
Below the point |
left |
To the left of the point |
right |
To the right of the point |
middle |
Centered on the point |
Point and line charts share the same position vocabulary and Vega-Lite mapping.
Multi-Metric Points¶
When y is a list, dbt Charts folds the measures into one color-coded series of points sharing the same x-axis. This is useful for comparing two measures against the same categories, though every additional measure is just another point at the same x distinguished only by color, so it reads best with a handful of categories rather than a dense continuous axis.
queries:
team_actual_vs_target:
columns: [team, actual, target]
values:
- ["Onboarding", 82, 90]
- ["Support", 76, 85]
- ["Success", 91, 88]
- ["Renewals", 68, 80]
- ["Escalations", 95, 92]
charts:
actual_vs_target:
query: team_actual_vs_target
type: scatter
title: Actual vs Target Score by Team
x: team
y: [actual, target]
rows:
- actual_vs_target
Size Scale¶
A size: channel maps values onto a mark-area range, [4, 361] px² by default, and starts the scale at zero. When a few values dwarf the rest, such as one account near 600,000 beside hundreds in the low thousands, the small marks shrink to dots. style.size sets the area range and how a value maps onto it.
type: scatter x: detected_at y: severity size: impacted_accounts style: size: range: [16, 1600] type: sqrt
rangeis the mark area in px², the unit ofstyle.marks.point.size:[low, high]with0 <= low < high.linearmaps values in proportion to the area from zero.sqrtcompresses a long tail while keeping zero as the anchor.logspans the smallest to the largest value, so everysize:value must be above zero; a value at or below zero is an error.sqrtmakes a mark's area grow with the square root of the value, so a value 4x larger draws 2x the area. This follows Vega-Lite, not d3's sqrt-on-radius idiom, where area is proportional to the value (that islinearhere).logneeds a range starting above 0, because it maps the smallest value tolow; withlow: 0that mark would draw with no area, so setrange, for example[9, 2500].- A
logorsqrtscale adds a footnote under the legend circles ("Log scale" or "Square-root scale");linearadds none. - The size legend draws its circles at the same range and scale type.
- A
style.conditionalrulesizestill overrides the channel for the points it matches. style.sizeneeds asize:field on the chart; set a default for every scatter instyle.charts.scatter.size.
Mark Fields¶
dbt Charts scatter charts are authored with type: scatter plus top-level channels such as x, y, color, size, and shape. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition blocks are rejected on the authored surface. Use top-level dbt Charts fields and the typed style: object.
Conditional styling¶
style.conditional restyles a point by the value in its own row, with no synthetic color:, size: or shape: column. 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 scatter style it applies:
type: scatter x: spend y: revenue style: conditional: is_outlier: - eq: true marks: point: color: "#c62828" size: 120 shape: diamond - default: true marks: point: opacity: 0.4
A rule can set only what varies per point:
| Field | Sets |
|---|---|
marks.point.color |
The point's fill, or its outline when unfilled |
marks.point.fill, marks.point.filled |
The interior of an unfilled point, and whether the point is filled |
marks.point.size, marks.point.shape |
The point's area and symbol |
marks.point.opacity, marks.point.stroke_width |
The point's opacity and outline width |
marks.text.font.color, marks.text.font.weight |
The point's value label |
axis_x.labels.font.color |
The date x-axis labels the rule matches (Conditional label colors) |
Anything else, such as marks.point.labels, is refused, and auto is not a value a rule can set.
- 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, unless both are in a multi-y
y:list. - On a multi-y chart a rule on a
y:column styles only that column's series. A rule on any other column styles every series at that x. - A rule
sizeorshapebeside an authoredsize:orshape:channel overrides the channel for the points it matches. The legend is unchanged. - Rules style the base layer only, never
layers:. conditionalis authored on the chart's ownstyle; atstyle.charts.scatterit is refused.