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
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
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
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
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
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
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
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
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
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
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
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.
firstandlastskip nulls. minandmaxread theyvalue, also whenlabels.fieldprints 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.sizekeeps 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
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
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.