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:24 UTC on 9 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 creates layered multi-metric lines.
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:24 UTC on 9 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:24 UTC on 9 Nov 2026 made withdbt Charts
▶

Layered Multi-Metric Lines

When y is a list, dbt Charts creates a layered line graph. This is useful when you want to compare two measures that share the same ordered x-axis.

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:24 UTC on 9 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 grid lines.

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 grid lines. 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 Grid Lines

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:24 UTC on 9 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:24 UTC on 9 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:25 UTC on 9 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: still cannot combine with y: [...]; dbt Charts rejects that at compile time.

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:24 UTC on 9 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:25 UTC on 9 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)500k1,000k1,500kWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:25 UTC on 9 Nov 2026 made withdbt Charts
▶

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,200k1,400k1,600k1,800k$1.26M$1.18M$1.31M$1.47M$1.69M$1.76MJan2024FebMarAprMayJun Data as of 14:25 UTC on 9 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.

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.
  • A scatter chart or a layer refuses 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.


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:25 UTC on 9 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:25 UTC on 9 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.