Skip to content

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
Ad Spend vs Pipeline Value152025303540Ad spend150200250Pipeline value Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
Deal Size vs Win Rate by Segment0$50,000$100,000$150,000$200,000Average Deal Size30%40%Win RateSegmentEnterpriseMid-MarketSMBStrategicOpen pipeline020406080100120140 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
Median Response Time by Team1.52.02.53.03.54.04.55.05.5HoursEscalationsRenewalsSuccessSupportOnboardingTeam Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
Confidence vs Lift0%10%20%30%40%50%60%70%80%Confidence10%15%Lift Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
Activation Rate vs Retention Rate50%55%60%65%70%75%80%85%Activation rate70%75%80%85%Retention rate Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
Actual vs Target Score by TeamEscalationsOnboardingRenewalsSuccessSupportTeam708090Actual, TargetActualTarget Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
  • range is the mark area in px², the unit of style.marks.point.size: [low, high] with 0 <= low < high.
  • linear maps values in proportion to the area from zero. sqrt compresses a long tail while keeping zero as the anchor. log spans the smallest to the largest value, so every size: value must be above zero; a value at or below zero is an error.
  • sqrt makes 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 is linear here).
  • log needs a range starting above 0, because it maps the smallest value to low; with low: 0 that mark would draw with no area, so set range, for example [9, 2500].
  • A log or sqrt scale adds a footnote under the legend circles ("Log scale" or "Square-root scale"); linear adds none.
  • The size legend draws its circles at the same range and scale type.
  • A style.conditional rule size still overrides the channel for the points it matches.
  • style.size needs a size: field on the chart; set a default for every scatter in style.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: true rule 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 size or shape beside an authored size: or shape: channel overrides the channel for the points it matches. The legend is unchanged.
  • Rules style the base layer only, never layers:.
  • conditional is authored on the chart's own style; at style.charts.scatter it is refused.