Skip to content

Line Graphs

Line graphs connect values across an ordered axis, usually time, to emphasize continuity, direction, rate of change, and overall shape; this family includes single- or multi-series lines and slope graphs. They are most useful when the main question is how something changes over time rather than how big isolated categories are.

dbt Charts line graphs use a small set of top-level shorthand fields together with style. In most cases, you only need query, type: line, x, and y to get started.

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 typed style objects.

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 Line Graph

These are the minimum fields required to render a basic line graph in dbt Charts.

dbt Charts field Maps to Vega-Lite Allowed values Notes
query data.values Query name or query reference Supplies the dataset.
type: line mark.type: "line" Literal line Selects the line mark.
x encoding.x.field Field name Ordered dimension, usually time.
y encoding.y.field Field name Numeric measure to plot.

Minimum Example

source: examples_db
charts:
  revenue_trend_minimal:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Weekly Revenue
    x: week
    y: revenue
rows:
  - revenue_trend_minimal
Weekly Revenue300   ​350   ​400KJan2024FebMarAprMayJun 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 line graph 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: line mark.type: "line" Literal line Selects the line mark.
x encoding.x.field Field name Usually a temporal or ordered field.
y encoding.y.field Field name or list of field names A list draws one line per measure on a shared y-axis.
title title.text String Chart title.
notes metadata String AI search/context metadata. Never rendered.
color encoding.color.field Field name Groups a line into multiple series.
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 encoding.y.format and encoding.y.axis.format Format string Numeric formatting for the y channel.
sort categorical axis sort Sort object Most useful when the x-axis is categorical.
connect none Column name Connects the points in that column's order instead of left to right. Needs a numeric x. See Connected Scatter.
projection top-level projection Vega-Lite projection name Available for Vega-Lite projection overrides.

Multi-Series Line Graph

This example adds color to split one line into multiple series while keeping the top-level chart definition compact.

source: examples_db
charts:
  revenue_by_product:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product
    type: line
    title: Revenue by Product
    x: week
    y: revenue
    color: product
rows:
  - revenue_by_product
Revenue by Product0   ​50   ​100   ​150KJan2024FebMarAprMayJun131.8K Gadget X111.7K Widget B61.8K Widget A46.7K Gadget Y35.8K Tool Z30.4K Widget C17.6K Tool A2.1K Gadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Axis Labels, Formatting, and Styling

This example shows common top-level chart fields such as labels and numeric formatting.

source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue Over Time
    x: week
    y: revenue
    x_label: Week
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
Revenue Over Time$300,000$350,000$400,000RevenueJan2024FebMarAprMayJunWeek Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Multi-Metric Lines

When y is a list, dbt Charts draws one line per measure on a shared y-axis. Use it to compare measures that share the same ordered x-axis and scale. Write each measure into the list rather than adding it as a layer: a layer draws an overlay, such as a target line or a second mark.

source: examples_db
charts:
  revenue_and_units:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue And Units Sold
    x: week
    y: [revenue, units_sold]
rows:
  - revenue_and_units
Revenue And Units Sold0   ​100   ​200   ​300   ​400   ​500KJan2024FebMarAprMayJun435.7K Revenue14.3K Units sold Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

A pivoted result (several measures grouped by a dimension) adds color: naming the dimension; see Multiple Measures by a Dimension.

Field Labels

Every surface that names a column (legend entries and titles, tooltip rows, axis titles) derives its text from the column name: units_sold becomes units sold (title-cased in legend titles). field_labels maps a column to the text to paint instead, written exactly as given. x_label/y_label and a layer's label still win on their own surface. A key that names no column of the chart's query is an error (checked when the query returns rows). Tables use style.columns.<col>.label instead.

charts:
  revenue_and_units_labeled:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue And Units Sold
    x: week
    y: [revenue, units_sold]
    field_labels:
      revenue: Revenue (USD)
      units_sold: Units shipped
rows:
  - revenue_and_units_labeled

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.

Legend and Gridlines

This example shows the small style surface for line graphs without changing the underlying data bindings.

source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue Over Time
    x: week
    y: revenue
    x_label: Week
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
Revenue Over Time$300,000$350,000$400,000RevenueJan2024FebMarAprMayJunWeek 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 the line graph is framed and read.

dbt Charts field Maps to Vega-Lite Allowed values Notes
style.axis_x config.axisX / encoding.x.axis AxisStyle object Per-axis styling (format, ticks, labels, grid, title).
style.axis_y config.axisY / encoding.y.axis AxisStyle object Per-axis styling.
style.axis_y.scale config.axisY.scale ScaleStyle object Y-axis scale config (zero, nice, domain, clamp).

Axis and Scale Controls

This example uses style to control the y-axis scale and tick density.

source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue Over Time
    x: week
    y: revenue
    x_label: Week
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
Revenue Over Time$300,000$350,000$400,000RevenueJan2024FebMarAprMayJunWeek Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Log Scale

Set style.axis_y.scale.continuous.type: log to plot a quantitative axis on a logarithmic scale, useful when values span multiple orders of magnitude (for example, exponential growth). Log scales are undefined at zero and for negative numbers; dbt Charts validates the domain at compile time and raises ERR_LOG_SCALE_REQUIRES_POSITIVE_DATA if any data value is zero or negative. Only use axis_y.scale.continuous.type: log on a measure you know is strictly positive.

source: examples_db
charts:
  revenue_log:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Revenue Over Time (Log Scale)
    x: week
    y: revenue
    x_label: Week
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            type: log
        labels:
          format: currency_whole
rows:
  - revenue_log
Revenue Over Time (Log Scale)$100,000$200,000$300,000$400,000$500,000$700,000$900,000RevenueJan2024FebMarAprMayJunWeek Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Endpoint Labels

A multi-series line graph names its series on the chart, anchored to each line's final point, rather than in a side legend. Each label reads the line's final value in the value axis's own number style, then its name (wrapping onto a second line when it is too wide; if a label does not fit in two lines or the rail runs out of vertical room, every label on the rail drops its value, so the rail never mixes labels with and without values, and a warning names the series that forced it; if the names would be cut even without their values, the values stay and only the end of the second line is cut, with a warning). On a layered chart the labels are names only. This is the default on every built-in theme; you don't switch it on. Set style.legend.position.edge to a side (top, bottom, left, right) to send the names back to a legend.

dbt Charts field Allowed values Notes
style.legend.position.edge auto, endpoints, top, bottom, left, or right Defaults to auto on every built-in theme: the chart names its series on the chart when it has more than one, and steps aside to a legend where a rail would not fit (for example a single series, a multiples: chart, a layered chart with a single base series, or a chart too narrow for the rail). A side keeps a legend there and prints no endpoint labels, at the chart, board or project (meta.yml) level; endpoints forces the labels on wherever a rail can render (multiples: charts refuse it). style.legend.visible: false hides the legend (under auto the labels stay; beside a side, nothing names the series), and true keeps a legend: under auto it turns the labels off, and only endpoints prints both.

style.endpoint_labels styles the labels themselves: label_offset is the gap between the plot and the labels.

When the label pane is on, the categorical legend turns off automatically: the two would encode the same series→color mapping twice. Authoring a legend.position side, or legend.visible: true under auto, keeps the legend instead and prints no labels; edge: endpoints with legend.visible: true prints both. The y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.

On narrow cards, endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.

Endpoint labels require a multi-series chart: either a color channel or a y: [field_a, field_b] list. On single-series lines there is only one series to name, so the feature is a no-op.

y: [...] composes with a color: column: the measures are crossed with the column's values, one series per value per measure, each named <value> - <measure>; see Multiple Measures by a Dimension. layers: overlay a y: [...] chart too: each layer takes the next free color after the folded series.

source: examples_db
charts:
  revenue_by_product:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product
    type: line
    title: Revenue by Product
    x: week
    y: revenue
    color: product
    style:
      legend:
        position:
          edge: endpoints

rows:
  - revenue_by_product
Revenue by Product0   ​50   ​100   ​150KJan2024FebMarAprMayJun131.8K Gadget X111.7K Widget B61.8K Widget A46.7K Gadget Y35.8K Tool Z30.4K Widget C17.6K Tool A2.1K Gadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Smoothing & Step Lines

style.marks.line.curve controls how adjacent points are joined, in place of the default straight-segment interpolation:

Value Effect
monotone A smooth curve that never overshoots the data; no wobble past a local min or max. A softer read than straight segments without misrepresenting the trend.
step On a categorical (nominal/ordinal) x-axis, a full-band-width plateau per x-value instead of a diagonal segment. On a continuous (temporal/quantitative) x-axis, Vega-Lite's own native step interpolate (points at band centers).
source: examples_db
charts:
  revenue_smoothed:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Weekly Revenue (Smoothed)
    x: week
    y: revenue
    style:
      marks:
        line:
          curve: monotone
rows:
  - revenue_smoothed
Weekly Revenue (Smoothed)300   ​350   ​400KJan2024FebMarAprMayJun Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Step Lines

curve: step on a categorical x column draws a full-band-width plateau. Adjacent plateaus are joined by a vertical bridge by default; set connect: false to leave them as disconnected segments instead.

Disconnected plateaus end flush with the band edge; each one is its own path, so the default round line cap would overhang every edge by half the stroke width and close up the gap between neighboring bands. Set disconnected_cap: round under marks.line to opt back into rounded ends. disconnected_width under marks.line (default 0.9) sets the share of the band each plateau spans, so neighboring plateaus at a similar value stay visually separate. A stroke.dasharray on a disconnected step line is scaled per plateau so ink lands on both edges: a whole number of dashes, separated by gaps, spans the plateau. The rendered lengths therefore differ slightly from the authored ones. Connected step lines are unaffected: they are a single continuous path, so stroke.cap still governs their two outer ends.

source: examples_db
charts:
  revenue_by_product_step:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: line
    title: Product Revenue (Step)
    x: product
    y: revenue
    style:
      marks:
        line:
          curve: step
          connect: false
rows:
  - revenue_by_product_step
Product Revenue (Step)0.5   ​1   ​1.5MWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Gaps in the Data

On a date or numeric x-axis, a line joins neighboring points with a straight segment, so a stretch with no rows would read as a smooth trend. The line breaks instead when the gap is large:

  • Far wider than the usual step. A gap more than three times the series' longest ordinary step breaks, as long as it spans more than 2% of the plot. Trading-day data that steps one day and three across a weekend stays joined; a two-week halt breaks.
  • A skipped period in evenly spaced data. When the points sit on a steady period, a gap that skips one breaks once it spans more than 15% of the plot. Five yearly points with one year missing break there. A series with no weekend rows does not count a weekend as a skipped period.

Evenly spaced points with nothing missing never break, however sparse, and a row with a null value always breaks the line. To join every gap, set connect: true:

type: line
x: month
y: revenue
style:
  marks:
    line:
      connect: true

A query that returns a row with a null value for each missing period breaks the line at every one of them, however small.

Halo

Multi-series lines that cross each other can be hard to trace right at the crossing point. style.marks.line.halo_multiplier draws a knockout-colored stroke behind each line, sized relative to the line's own stroke width, so crossings stay legible. Set it to 0 to disable the halo.


Value Labels

Show the numeric value beside each data point on a line chart by enabling style.marks.line.labels.visible.

source: examples_db
charts:
  revenue_labeled:
    query:
      sql: |
        SELECT DATE_TRUNC('month', date) AS month, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY month ORDER BY month
    type: line
    title: Monthly Revenue
    x: month
    y: revenue
    style:
      marks:
        line:
          labels:
            visible: true
            position: top    # top | bottom | left | right | middle
            format: "$.3~s"  # short SI labels fit; omit to inherit axis_quantitative.format
            font:
              color: "#6b7280"
              size: 11
rows:
  - revenue_labeled
Monthly Revenue1.2   ​1.4   ​1.6   ​1.8M$1.26M$1.18M$1.31M$1.47M$1.69M$1.76MJan2024FebMarAprMayJun Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Set font.color: series under labels to paint each label in its series' color, on line, area and point charts. On a layer, series follows the color its mark is drawn in: an authored marks.point.color or line stroke color first, else the series color. Where that color would read below 3:1 against a bar or the background behind it, the label keeps its hue at the nearest lightness that reaches 3:1.

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
auto Same as leaving it unset: the label places itself

Leave position unset and each label places itself: it starts above its point, stays centered on it where it can, and steps further out or to another side to keep a gap from the lines, points, baselines, axis labels and other labels, preferring the side nearest its own series. A label prefers a spot off the gridlines, but a gridline never costs it a place. Points that sit on top of each other take one label, on the series drawn on top. A final point's label sits beside a right axis without endpoint labels, at its own height when nothing collides. With labels on, a series' endpoint label prints its name alone and the last point keeps its value, and a point on the value axis whose label would repeat a tick label shows none either. A label with no clear spot is not drawn; hovering the point still shows the value, and WARN-VALUE-LABELS-THINNED fires when more than a quarter of a chart's labels were dropped. On a line with no point markers, WARN-VALUE-LABELS-NO-MARKERS suggests showing the points. Setting position pins every label there, never moved or dropped.

When a chart has several series, their first labels sit just outside the plot, beside their points, in the axis numbers' column on a left axis or in an indent on a right one. A label outside the plot stays at its point's height: if that spot is taken, it comes back into the plot.

Label Only Some Points

Set visible to a list of anchors to print only those values of each series, enough to read a scale without labeling every point. The list takes first, last, min and max in any combination; visible: last is the same as [last].

source: examples_db
charts:
  revenue_range:
    query:
      sql: |
        SELECT DATE_TRUNC('month', date) AS month, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY month ORDER BY month
    type: line
    title: Monthly Revenue
    x: month
    y: revenue
    style:
      marks:
        line:
          labels:
            visible: [min, max]
            format: "$.3~s"
rows:
  - revenue_range
  • Each series and each small-multiples panel picks its own anchors. first and last skip nulls.
  • min and max read the y value, also when labels.field prints another column. A tie labels every tied point, so a flat series under [min, max] labels them all.
  • A point two anchors name prints once.
  • Automatic dots give way to a dot on each anchored point; a set marks.point.size keeps every dot.
  • Where an endpoint label already shows a series' last value, that point gets no value label.
  • Anchors work on line, area and scatter layers too, picked along the chart's x within each of the layer's color series. A scatter chart (and its layers) and a bar layer refuse anchors.

dx/dy (pixel offsets) are also available under labels to nudge a label off its default position. Line and point charts share the same position vocabulary and Vega-Lite mapping.

On a curve: step line over a categorical x, the mark is a plateau spanning the whole band rather than a point, so left and right resolve against the band's leading and trailing edge instead of the datum at its center, otherwise the caption would land on top of the mark it is meant to sit beside. This tracks the real band width, so no dx is needed to clear the mark at any board width or category count. Where the band is the first or last in the domain and the preferred side has no room, that one label falls back to top, keeping it inside its own band rather than over its neighbor's. top, bottom and middle are unaffected: band width is horizontal, and the band's center is the mark's center.


Overlays (layers:)

Add a layers: list to a line chart to overlay additional marks: a bar for context, a scatter reference, or a second line on a separate y-axis. The base line chart owns the x-axis, frame, title, legend, and sort. Each layer contributes its own mark and legend entry.

charts:
  trend_with_target:
    type: line
    x: month
    y: actual
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
          title: Target
        style:
          marks:
            line:
              stroke:
                width: 2
                dasharray: "4 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.

For a dual-axis example where the overlay draws from a separate query:

queries:
  monthly_signups:
    columns: [month, signups]
    values:
      - ["2024-01", 480]
      - ["2024-02", 560]
  weekly_conversion:
    columns: [month, conversion_pct]
    values:
      - ["2024-01", 12.5]
      - ["2024-02", 14.2]
charts:
  signups_and_conversion:
    type: line
    x: month
    y: signups
    query: monthly_signups
    layers:
      - type: line
        y: conversion_pct
        label: Conversion (%)
        query: weekly_conversion
        axis_y:
          position: right
          title: Conversion (%)
          scale:
            domain: [0, 100]

Layer x-values from a separate query extend the base x-scale automatically; no x_domain field is needed or accepted.

Layer fields: type, y, label, color, query, x, axis_y, style (marks-only patch). sort: is base-only.


Conditional styling

style.conditional restyles the points, value labels and line segments by the value in its own row, so a presentation choice stays out of the query. 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 line chart style it applies:

type: line
x: month
y: revenue
style:
  marks:
    point:
      size: 60
  conditional:
    is_forecast:
      - eq: true
        marks:
          point:
            opacity: 0.4
          text:
            font:
              color: "#8a8a8a"

A rule can set only what varies along the series:

Field Sets
marks.point.color, marks.point.fill, marks.point.filled The point's paint; fill applies when filled: false
marks.point.size, marks.point.shape The point's size and symbol
marks.point.opacity, marks.point.stroke_width The point's opacity and ring width
marks.text.font.color, marks.text.font.weight The point's value label
marks.line.stroke.color, marks.line.stroke.width, marks.line.stroke.dasharray The line segments between matching points
axis_x.labels.font.color The x-axis labels the rule matches (Conditional label colors)

curve, connect, labels and marks.rule describe the whole series, so they are not conditionable and a rule that sets one is refused (for example marks: {line: {curve: step}}).

Restyling the line

The line is drawn between points, so a segment takes a rule's marks.line style only when both of its end points match the rule. A run of matching points restyles the segments inside it, a single matching point restyles no line, and the segment that steps into the run keeps the base style. Where two end points resolve different values for a key, the base style is used for that key.

The curve is computed over the whole series and then cut at the points, so a restyled line has exactly the shape of the plain one. A basis curve, a step curve over a category axis and a chart with connect: cannot be cut and are refused.

To draw a forecast as a dashed gray line starting at the last actual month, make the boundary point match too. Have the query compute a column that is true from the last actual month on:

select
    month,
    revenue,
    month >= date '2024-06-01' as from_last_actual
from monthly_revenue
type: line
x: month
y: revenue
style:
  conditional:
    from_last_actual:
      - eq: true
        marks:
          line:
            stroke:
              color: "#8a8a8a"
              dasharray: "6 4"
  • Each point is tested against its own row, so on a multi-series chart a rule on team or is_forecast styles that series' points individually.
  • A rule's size overrides the chart's point size at the matching rows: size: 0 hides a point, and a positive size draws one where the chart's marks.point.size is 0.
  • 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.
  • Rules style the base layer only, never layers:.
  • conditional is authored on the chart's own style; at style.charts.line it is refused.

Authored Surface

dbt Charts line charts are authored with type: line plus top-level channels such as x, y, and color. 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.


Multiple Measures by a Dimension

A pivoted result, several measures as columns grouped by a dimension, is the shape every semantic layer and most warehouse rollups produce. Add color: naming the dimension and each of its values is crossed with each measure: two measures by three categories draws six lines, each named <category> - <measure>. The legend, endpoint labels, and tooltip all read those composite names.

source: examples_db
charts:
  order_size_by_category:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, category, AVG(revenue) AS avg_order_value, MAX(revenue) AS largest_order FROM ecommerce_orders GROUP BY week, category ORDER BY week, category
    type: line
    title: Average and Largest Order by Category
    x: week
    y: [avg_order_value, largest_order]
    color: category
rows:
  - order_size_by_category
Average and Largest Order by Category1,0001,5002,0002,5003,0003,500Jan2024FebMarAprMayJunAccessories - Largest orderTools - Largest orderElectronics - Largest orderTools - Avg order valueAccessories - Avg ordervalueElectronics - Avg order value Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Connected Scatter

A line sorts its points by a numeric x before it draws them, because a trend reads left to right. A trajectory does not: with both axes carrying a measure, the path doubles back, and the loops are the point. Set connect: to a column, such as connect: year, and the line passes through the points in that column's ascending order.

queries:
  driving_and_gas:
    columns: [year, miles_per_person, gas_price]
    values:
      - [1996, 8000, 1.2]
      - [1999, 9200, 1.1]
      - [2002, 9600, 1.5]
      - [2005, 9800, 2.4]
      - [2008, 9100, 3.3]
      - [2011, 8800, 3.5]
      - [2014, 9000, 3.4]
      - [2017, 9500, 2.4]

charts:
  driving_vs_gas:
    query: driving_and_gas
    type: line
    title: Driving and the Price of Gas
    x: gas_price
    y: miles_per_person
    connect: year
rows:
  - driving_vs_gas
Driving and the Price of Gas8,0008,5009,0009,50011.522.533.5 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Points that tie on the connect column keep the order the query returned them in. A null in the column is an error, since that point has no place in the path. connect is for a numeric x; a date or category x has an order of its own, and the chart refuses the key there. Without it, a line connects its points in x order. It is separate from the step-line connect under style.marks.line, which joins or splits a step line's plateaus.