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 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
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
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
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
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: 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
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
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
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.
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.
- Anchors work on
line,areaandscatterlayers too, picked along the chart's x within each of the layer'scolorseries. A scatter chart (and its layers) and abarlayer 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:
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
teamoris_forecaststyles that series' points individually. - A rule's
sizeoverrides the chart's point size at the matching rows:size: 0hides a point, and a positive size draws one where the chart'smarks.point.sizeis 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: truerule must be last and applies only when no other rule matched. - The column must be in the query result. Rules on two columns cannot set the same field, unless both are in a multi-y
y:list. - On a multi-y chart a rule on a
y:column styles only that column's series. A rule on any other column styles every series at that x. - Rules style the base layer only, never
layers:. conditionalis authored on the chart's ownstyle; atstyle.charts.lineit 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
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.