Bar Charts¶

Bar charts encode values as lengths measured from a common baseline, which makes them one of the most fundamental tools for comparison; this family includes horizontal bar charts and vertical column charts. Horizontal bars are especially good for ranking categories with long labels, while vertical columns are especially good for showing change over simple time steps.

dbt charts bar charts use a small set of top-level shorthand fields together with style. By default, style.orientation is auto: dbt charts picks horizontal for categorical x (nominal/string labels) and vertical for continuous x (temporal, quantitative, date-like ordinal, or time-unit bucketed). The rule is type-driven, not viewport-driven — orientation reflects what the data is, not how wide the chart happens to be. Set style.orientation: vertical or style.orientation: horizontal to lock in a specific orientation. See Axis Labels — Smart Layout for how the engine picks orientation and label tilt automatically when style.orientation is left at its default.

A chart's control surface is the full set of authored properties available on a single chart. In dbt charts, that surface is primarily top-level chart fields plus a typed style object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the YAML Schema Reference.

Minimum Required for a Bar Chart¶

These are the minimum fields required to render a basic bar chart in dbt charts. With a nominal x-axis (category strings), the default result is a horizontal bar chart; with a continuous x-axis (temporal, quantitative, or date-like ordinal), the default is a vertical column chart. See Axis, Scale, and Orientation for the rule, or set style.orientation explicitly to override.

dbt charts field	Maps to Vega-Lite	Allowed values	Notes
`query`	`data.values`	Query name or query reference	Supplies the dataset.
`type: bar`	`mark.type: "bar"`	Literal `bar`	Selects the bar mark.
`x`	`encoding.x.field`	Field name	Category, discrete field, or temporal field.
`y`	`encoding.y.field`	Field name	Numeric measure to compare.

Minimum Example¶

source: examples_db
charts:
  product_revenue_columns:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - product_revenue_columns

▶

Top-Level Chart Fields¶

These are the top-level chart properties you set directly on a bar chart before you get into nested properties under style.

dbt charts field	Maps to Vega-Lite	Allowed values	Notes
`query`	`data.values`	Query name or query reference	Query results become the plotted dataset. Use pre-aggregated data with one row per plotted key.
`type: bar`	`mark.type: "bar"`	Literal `bar`	Standard bar or column chart.
`x`	`encoding.x.field`	Field name	Usually the category field, or a temporal field for time-unit column charts.
`y`	`encoding.y.field`	Field name or list of field names	Usually the numeric measure, even when the final chart is horizontal. A list creates layered multi-metric bars.
`title`	`title.text`	String	Chart title.
`description`	metadata	String	Available for tooling and docs.
`color`	`encoding.color.field`	Field name	Adds series grouping or composition.
`x_label`	`encoding.x.title`	String	Custom x-axis title.
`y_label`	`encoding.y.title`	String	Custom y-axis title.
`format`	quantitative value-axis format	Format string	Numeric formatting for the value axis. In horizontal bars, that value axis is rendered on `x`.
`sort`	categorical axis sort	Sort object	Most useful for ranked bar charts.

Vertical Columns and Horizontal Bars¶

This example shows the family's two main forms side-by-side: a vertical bar chart (also called a column chart), and the same data rendered horizontally. Both pin style.orientation explicitly so the contrast is what's on the page; left at auto, this nominal x would render horizontal by default.

source: examples_db
queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
charts:
  product_revenue_columns:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: vertical

  product_revenue_bars:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: horizontal
rows:
  - product_revenue_columns
  - product_revenue_bars

▶

Labels and Ranking¶

This example keeps the chart definition compact while showing the top-level fields most readers use in practice: labels, formatting, and sorting.

source: examples_db
charts:
  ranked_products:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Top Products by Revenue
    description: A sorted product ranking shown as horizontal bars.
    x: product
    y: revenue
    x_label: Product
    y_label: Revenue
    sort:
      by: revenue
      order: desc
    style:
      number_format: currency_whole
      orientation: horizontal
rows:
  - ranked_products

▶

Layered Multi-Metric Bars¶

When y is a list, dbt charts creates a layered bar chart. This is most useful when the metrics share a similar scale and the comparison is more important than stacking.

queries:
  product_metrics:
    columns: [product, revenue, profit]
    values:
      - ["Gadget X", 18350, 4200]
      - ["Gadget Y", 30490, 7600]
      - ["Tool Z", 34900, 9100]
      - ["Widget A", 66300, 18500]
      - ["Widget B", 85680, 24100]

charts:
  layered_product_metrics:
    query: product_metrics
    type: bar
    title: Revenue and Profit by Product
    x: product
    y: [revenue, profit]
rows:
  - layered_product_metrics

▶

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 bar charts without changing the underlying data bindings.

source: examples_db
charts:
  category_columns_styled:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: bar
    title: Revenue by Category
    x: category
    y: revenue
    color: category
    style:
      stack: zero
      legend:
        visible: false
      axis:
        grid:
          visible: false
rows:
  - category_columns_styled

▶

Axis, Scale, and Orientation¶

All presentation config lives under style. This is where the family distinguishes default vertical columns from horizontal bars.

dbt charts field	Maps to Vega-Lite	Allowed values	Notes
`style.orientation`	bar orientation transform	`auto` (default), `vertical`, or `horizontal`	`auto` picks `horizontal` for categorical x, `vertical` for continuous x (temporal/quantitative/date-like ordinal); `vertical` and `horizontal` lock the orientation.
`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). Use `axis_x.scale` for categorical band padding.
`style.stack`	`encoding.y.stack`	`"none"`, `"zero"`, `"normalize"`, `"center"`	Stacking behavior. Omit `stack` when a `color` field is present to get the default side-by-side grouped layout. Set `"none"` for grouped (side-by-side), `"zero"` for stacked-from-baseline, `"normalize"` for 100% stacked, `"center"` for diverging stacks. (Within-group spacing of grouped bars is controlled by `style.overlap`, not `stack`.)
`style.stack_order`	`encoding.order`	`"value"` (default), `"data"`, `"alphabetical"`	Z-order of stacked segments. `"value"` puts the largest aggregate at the baseline. `"data"` follows SQL row order (orientation-stable not guaranteed). `"alphabetical"` sorts by color field name. Ignored when stacking is off or no `color` is set.
`style.overlap`	bar `xOffset`/`yOffset` spacing	`"auto"` (default), `"none"`, `"flush"`, `"partial"`, `"full"`, or a number	Within-group spacing for grouped bars (a `color` field, not stacked). `"auto"` adapts to the series count — `partial` (25% overlap) at 2 series, `none` (small gap) at 3+. `"none"` gaps, `"flush"` touches, `"partial"` overlaps 25%, `"full"` coincides. A number is a fraction of bar width: `>0` overlaps, `0` touches, `<0` gaps. Positive overlap is only valid for 2 series — overlapping 3+ series buries the middle one, so it raises an error (use `none`/`flush` for 3+, or rely on `auto`). Setting any overlap with an active stack mode (`"zero"`/`"normalize"`/`"center"`) is also an error.
`style.marks.bar.band_width`	`mark.width.band`	`float` (fraction of the band, `0`–`1`)	Fraction of the available band each bar fills. Lower it to thin bars out and open up whitespace between categories without changing `overlap`, which only governs spacing within a grouped-color band.

Bar Width¶

This example thins the bars to 40% of their band, leaving visible whitespace between categories.

source: examples_db
charts:
  product_revenue_thin:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          band_width: 0.4
rows:
  - product_revenue_thin

▶

Orientation and Axis Controls¶

This example uses style to turn a column chart into a horizontal ranking chart while also adjusting axis formatting and label space.

source: examples_db
charts:
  product_revenue_ranked:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Product Revenue Ranking
    x: product
    y: revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      number_format: currency_whole
      axis_x:
        labels:
          max_width: 140
      axis_y:
        scale:
          nice: true
rows:
  - product_revenue_ranked

▶

Endpoint Labels and the Top-Row Series Rail¶

A multi-series bar names its series on the chart, anchored to each segment, rather than in a side legend. This is the default on every built-in theme — you don't switch it on. Multi-series bars come from either a color channel or a y: [field_a, field_b] list; both layouts render the endpoint rail. Where the labels go depends on the orientation:

Vertical stacked column charts get one label per segment in a side pane, anchored to each segment's vertical midpoint in the rightmost column. The chart pane and label pane sit side-by-side in an hconcat.
Horizontal stacked bar charts get a single rail of labels above the top row of the chart — one label per series, centered horizontally on its segment's midpoint within the top categorical row. The chart pane and rail sit stacked in a vconcat. The bottom row's value axis still carries the numeric measure labels.

The asymmetry follows from the reading direction: vertical stacks read top-to-bottom along the measure axis, so per-segment side labels feel natural; horizontal stacks read left-to-right inside one row, so a single label rail above the top row is the direct equivalent.

dbt charts field	Allowed values	Notes
`style.endpoint_labels.visible`	`true` or `false`	Defaults to `true` on every built-in theme. Set `false` per-chart to send the series names back to a legend; set `true` to force the rail onto a shape it steps aside from (below).

When the label pane or rail is on, the categorical legend turns off automatically — the two would encode the same series→colour mapping twice. On the vertical layout, the y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.

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

When neighboring labels in the horizontal rail would overlap, the resolver lifts the right-hand label by one line-height (vertical dodge). The leftmost label always sits at the base row — that determinism is part of the contract. Dodging caps at three rows above base; if all three rows still collide, the resolver accepts overlap deterministically rather than dropping a label silently.

When a bar falls back to a legend instead¶

The rail has to be able to name every series, or it names some of them and quietly misleads. An authored sort: is fine when it sorts by a measure — each rail anchors on the rendered domain, so it follows the sort rather than refusing it. Sorting by a non-numeric column is the exception: Vega-Lite orders that domain by concatenating the strings, which the rail cannot reproduce, so the chart takes a legend instead. Where it can't, the chart keeps its legend — placed above the plot, untitled, reading in the same order as the bars. A bar steps aside from direct labelling when:

It's grouped — explicit stack: none, or the grouped-by-default when stack is omitted and a color field is present. Every series' last bar rises from the same baseline to a similar height, so the labels collide into one another.
It has no color encoding and no y: [...] list — a single series has nothing to name.

You cannot combine y: [...] with an authored color: channel or layers:; dbt charts rejects that combination at compile time. - color: names the same field as x:, or a series is missing from the column the rail anchors on (a trailing null, say). Either way some series would go unnamed. - It carries multiples: — see Small Multiples. - The measure goes negative — a stacked segment crossing zero has no meaningful cumulative midpoint to anchor to. - It's horizontal and stack: center — that rail anchors on the cumulative 0..Σ axis, which the diverging centre-stack domain doesn't have. - It has layers: — the rail walks the base chart's own series, so an overlay layer would be left anonymous.

Writing style.endpoint_labels.visible: true on the chart itself overrides all of these: an author who asks for the rail on one of these shapes gets it, or gets a rendering error naming the conflict where the shape genuinely can't carry it.

Vertical Stacked Columns¶

source: examples_db
charts:
  region_revenue_by_category_vertical:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (vertical stack)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: vertical
      endpoint_labels:
        visible: true

rows:
  - region_revenue_by_category_vertical

▶

Horizontal Stacked Bars¶

source: examples_db
charts:
  region_revenue_by_category:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (stacked by Category)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: horizontal
      endpoint_labels:
        visible: true

rows:
  - region_revenue_by_category

▶

Value Labels¶

Show the numeric value above (or inside) each bar by enabling style.marks.bar.labels.visible.

source: examples_db
charts:
  product_revenue_labeled:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          labels:
            visible: true
            position: top      # above | top | middle | middle_aligned | bottom
            format: ",.0f"     # omit to inherit axis_quantitative.format (the measure-axis format, e.g. ".3~s")
            font:
              color: "#6b7280"
              size: 11
rows:
  - product_revenue_labeled

▶

Position values:

Value	Placement
`above`	Outside, past the bar end
`top`	Just inside the bar's end — the theme default
`middle`	Centered in the bar
`middle_aligned`	Every label at one shared height, so a row of them reads as a line
`bottom`	Just inside the baseline end

On a stacked bar, middle centers each label in its own segment rather than in the whole stack — use it when every segment carries a value. above has no room above an individual segment, so it renders as top. middle_aligned is not meaningful per-segment and raises an error; use middle.

On vertical bars, a label whose segment is too short to hold it is dropped rather than drawn across its neighbors, so a stack with one thin band shows the labels that fit and omits the one that does not.

dx/dy (pixel offsets) are also available under labels to nudge a label off its default position. To enable labels for all bar charts at theme level, set marks.bar.labels.visible: true in your theme YAML.

Overlays (`layers:`)¶

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

charts:
  revenue_vs_target:
    type: bar
    x: month
    y: revenue
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
        style:
          stroke:
            width: 2

Layer fields:

Field	Description
`type`	Mark type: `bar`, `line`, `area`, or `scatter`
`y`	Measure column for this layer
`label`	Legend label (defaults to the column name)
`color`	Data field for color encoding on this layer
`query`	Override the base query for this layer's data
`x`	X field for this layer (values extend the base x-scale)
`axis_y`	`{position: left\|right}` plus per-side scale/format
`style`	Marks-only style patch (e.g. `stroke.width`, `fill.opacity`)

sort: and x-axis chrome are base-only — layers inherit x ordering.