Tables and Text¶

Tables present values directly in rows and columns, making lookup, exact reading, and dense comparison possible; this family includes plain text tables, colored tables, and spark tables. They are most useful when the reader needs exact numbers, many values at once, or a structured reference view rather than a strongly shaped visual pattern.

This page will also cover other data-powered text-like outputs that are not really Vega-Lite charts at all, such as KPI blocks, large single-value callouts, and future narrative or AI-generated summary text. In other words, this family is not just about tables as rows and columns; it is about text-oriented outputs that are driven by data and are often used when exact reading, summarization, or direct communication matters more than visual encoding.

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 table, KPI, spark, and spark_bar property coverage, see the YAML Schema Reference.

Table Charts¶

Use type: table when exact values, scanning, and dense comparison matter more than mark-based trend reading.

Minimum Required for a Table¶

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`query`	table data rows	Query name or query reference	Supplies the dataset.
`type: table`	table SVG renderer	Literal `table`	Selects the table renderer.

Table-Specific Style¶

Table-specific style fields go directly under style: (e.g. style.row_numbers.visible, style.columns). Chart-level style: is typed as TableChartStylePatch — its fields sit at the root of the chart's style: block. Using style.table.* nesting raises a validation error (extra inputs are not permitted).

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`style.columns`	per-column display config	Mapping of column name → config object	Lets you choose columns explicitly and configure labels, formatting, width, alignment, header links, and inline sparks. Use `column_name: {}` for a bare column with defaults.
`style.column_defaults`	table-wide column defaults	`TableColumnDefaultsConfig` object	Sets `label`, `width`, `align`, `format`, `background`, and `font` for all columns; per-column entries override field-by-field.
`style.header_overflow`	header overflow behavior	`clip`, `truncate`, `wrap-two` (default), or `wrap`	Controls how long table headers clip, truncate with ellipsis, or wrap. Headers wrap to two lines unless you set this.
`style.background`	chart SVG background wrapper	Color value	Applies a chart-level background fill behind the rendered table SVG.
`style.column_layout.width_similarity_threshold`	column cluster equalization threshold	Float `0.0`–`1.0` (default `0.8`)	Auto-width columns whose min/max ratio ≥ this value are snapped to a shared width before budget allocation. `0.8` = within ~20% get equalized; `1.0` = disabled (pure proportional); `0.0` = all auto-columns equal.
`style.symbol_mode`	currency-prefix / magnitude-suffix placement on numeric columns	`anchors` (theme default) or `all`	`anchors` shows the full formatted value only on the first data row and on summary/total rows, stripping the prefix from plain middle rows — the anchor rows carry the unit so the reader doesn't need it repeated on every line. The magnitude suffix (K/M/B) also strips from middle rows when the column's values share one common magnitude (see Number Formatting below); otherwise it stays on every row, since it then still carries per-row value. `all` shows the full formatted value (prefix + number + suffix) on every row.

To disable column equalization for a chart that needs strict proportional sizing — for example, a revenue waterfall where the column widths carry meaning — set the threshold to 1.0:

style:
  column_layout:
    width_similarity_threshold: 1.0  # disable equalization; use strict proportional widths

Every built-in theme defaults symbol_mode to anchors — a currency or percent symbol only at the top and bottom of a numeric column. To show the symbol on every row instead, set symbol_mode: all:

style:
  symbol_mode: all  # "$1,234" on every row instead of just the first data row and the total row

Row Presentation (`style.row`)¶

The style.row block controls body-row defaults and per-role overrides for summary and total rows. The singular row name avoids confusion with the board-level rows: layout key.

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`style.row.role`	column id for per-row role	Column name (string)	Per-row value: `value`, `summary`, or `total`.
`style.row.height`	body row height (px)	Number	Body row height.
`style.row.rule.width`	row separator width (px)	Number	Row separator width.
`style.row.rule.color`	row separator color	Color value	Sets the row separator color; overrides the theme default.
`style.row.roles.summary.font.weight`	summary row font weight	`"400"`, `"500"`, `"600"`, `"700"`	Summary-row font weight.
`style.row.roles.summary.background`	summary row fill	Color value	Fill behind summary rows.
`style.row.roles.total.font.weight`	total row font weight	`"400"`, `"500"`, `"600"`, `"700"`	Total-row font weight.
`style.row.roles.total.background`	total row fill	Color value	Fill behind total rows.

style:
  row:
    role: kind              # column whose per-row value is the role
    height: 15
    rule:
      width: 2
      color: "#D32F2F"
    roles:
      summary:
        font:
          weight: "500"
      total:
        font:
          weight: "700"
        background: "#F5F5F5"

Row Numbers (`style.row_numbers`)¶

The style.row_numbers block injects a synthetic leading column that numbers data rows 1, 2, 3, ... — the same presentation as Excel, Google Sheets, and Looker's show_row_numbers. The column is transparent to style.columns (authors don't list it), to conditional_formatting rules keyed by column name (no rules target it), and to the data pipeline (it is a chart-layer concern, not a query column).

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`style.row_numbers.visible`	toggle on/off	`true` or `false`	Default `false` — off unless set.
`style.row_numbers.header`	column header text	String	Default `"#"`.
`style.row_numbers.align`	cell text alignment	`left` or `right`	Default `right`, matching numeric convention.

style:
  row_numbers:
    visible: true   # minimum v1 opt-in
    header: "#"     # defaults; include to override
    align: right

Pagination behavior: numbering is continuous across pages. Page 2 of a 100-per-page table starts at row 101; it never resets to 1. The column width sizes against the total row count (not the per-page count), so page 1 and page 5 of a 200-row table have the same row-number column width.

Summary / total rows: the row-number cell is blank on rows tagged as summary or total (via style.row.role). The sequence counts data rows only.

Table Pagination¶

Tables support client-side row pagination via style.pagination. This controls how many rows are visible per page — it is a presentation concern, distinct from query-level limit which controls how many rows are fetched.

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`style.pagination`	enables row paging	Object	Use the object form shown below.
`style.pagination.enabled`	toggle pagination on/off	`true` or `false`	Defaults to `true` when pagination is present.
`style.pagination.page_rows`	rows per page	Positive integer	Optional; when omitted the renderer uses its default.

Use the full object form:

style:
  pagination:
    enabled: true
    page_rows: 25

Design note: style.pagination is purely presentational. Use query-level limit when the intent is to fetch fewer rows. The Looker migration exporter maps limit_displayed_rows / num_rows to style.pagination.page_rows, preserving the distinction between data truncation and UI paging.

Conditional Formatting (`conditional_formatting`)¶

Tables (and other chart types) support cell-level conditional styling through the chart-level conditional_formatting: block — keyed by query column name, with a when: list evaluated top-to-bottom like spreadsheet rules. This is the canonical mechanism for changing a cell's background, font.color, or font.weight based on a predicate over its value (thresholds, equality, a default catch-all). There is no separate cell_style field on style.columns[] — conditional decisions live here. (style.columns[].background/.font can also resolve per-row from another column's raw value with no predicate involved — see Per-row style from another column below.)

Predicate	Meaning
`gte: <number>`	value is greater than or equal to
`gt: <number>`	value is strictly greater than
`lte: <number>`	value is less than or equal to
`lt: <number>`	value is strictly less than
`eq: <value>`	value equals (string or number)
`default: true`	catch-all; place last

Each when entry can set background (color), font.color (color), font.weight ("400" … "700"), and glyph (a character prepended to the cell value). Rules are evaluated per-row, per-column, in list order; every matching rule (other than default: true) contributes its style keys, and later matches win over earlier ones for a given key — the last gte: you list beats an earlier one that also matches.

charts:
  cf_revenue_table:
    type: table
    query: product_category_revenue
    conditional_formatting:
      revenue:
        when:
          - gte: 50000
            background: "#dcfce7"
            font:
              color: "#166534"
              weight: "bold"
          - gte: 30000
            background: "#e0f2fe"
          - default: true
            background: "#fef3c7"
      category:
        when:
          - eq: Electronics
            background: "#ede9fe"
          - eq: Accessories
            background: "#cffafe"
          - default: true
            background: "#f4f4f5"

Glyph tone¶

A rule that sets glyph can color it either way: glyph_color takes a raw color, or tone names a semantic role (positive, negative, warning, info) that resolves through the theme's tone palette. Prefer tone — it adapts across themes, and it is the same vocabulary KPI cards use. Both require glyph; an explicit glyph_color wins if you set both.

charts:
  tone_revenue_table:
    type: table
    query: product_category_revenue
    conditional_formatting:
      revenue:
        when:
          - gte: 50000
            glyph: "▲"
            tone: positive
          - lt: 30000
            glyph: "▼"
            tone: negative
          - default: true
            glyph: "●"
            tone: info

tone colors the glyph only — it does not repaint the cell's text or background. Use font.color and background for those, or scale: for a continuous gradient.

Why chart-level, not column-level: rules are keyed by column name inside the conditional_formatting block, which keeps style.columns[] focused on layout (label, format, width, align, link, spark) and conditional decoration discoverable in one place. Authors who think "I want red below zero on the revenue column" find one block instead of digging into per-column blocks.

For value-driven gradients (continuous color across a numeric range), see the scale: config — separate from when: rules. Both compose under conditional_formatting.

Table Column Config¶

style.column_defaults sets shared defaults applied to every column in style.columns. Per-column entries override field-by-field:

style:
  column_defaults:
    label: " "
    width: 36
    align: center
  columns:
    c1: {}
    c2: {}
    c3:
      background: "#fee2e2"  # overrides background; label/width/align come from defaults

When all columns share the same presentation (labels, width, alignment), you only write the defaults once and use empty config objects for columns that only inherit defaults.

Each style.columns.<column_name> entry can set:

column
label
format
width — hard pin to an exact pixel value or percentage (e.g. 200 or "20%"). Cannot be combined with max_width:.
max_width — cap on auto-sized text columns (see below). Cannot be combined with width:.
align
header_link
link — cell-level hyperlink; supports a static URL, a column ID (uses per-row value), or a template with {{ column_id }} placeholders
spark
swatch — render the cell as a small color chip instead of text (see below)
background — a hex color (or transparent/none), or a column ID (uses per-row value — see below)
font — font.color and font.weight accept a column ID the same way background does

style.column_defaults supports label, width, align, format, background, and font. Data-dependent fields (link, header_link, spark, swatch, scale, glyph) are not available as defaults.

Per-row style from another column¶

background, font.color, and font.weight resolve column-ID-first, the same way link does above: if the configured value matches one of the query's column names, the cell uses that row's value in the named column instead of treating the string as a literal. This lets a helper column computed by the query drive per-row cell styling directly, with no when: predicate:

style:
  columns:
    account:
      background: status_color   # per-row: uses each row's status_color value, not the literal string "status_color"

If the configured value doesn't match a column name, it's used as a literal — a hex string (transparent/none also accepted) for background, or "bold" / "400" … "700" for font.weight. Neither field raises on an unrecognized value: an unresolvable color (a mistyped column name, or an unsupported literal like a CSS color name) silently paints no background instead, an unrecognized font.color silently leaves the cell's default ink color, and an unrecognized weight silently falls back to the default text weight — check the rendered output rather than relying on a compile-time error. The same applies to a NULL or empty helper-column value: the cell renders unstyled, with no error.

Precedence: a matching conditional_formatting when: rule on the same column overrides the column-ID value; with no match, the column-ID value stands. Don't combine column-ID background/font.color with scale: on the same column — scale: reads the unresolved configured string as its own base value, so a column-ID reference (not a real color) fails scale:'s color check and silently discards the background/color for every row, not just unmatched ones.

This is a narrower mechanism than conditional_formatting (above): it always uses the raw value of another column, with no predicate. Reach for conditional_formatting when the styling decision depends on a threshold or comparison; reach for this when the query already emits the exact style value per row.

Color Swatch Columns¶

Set swatch: true on a column whose cell values are CSS color strings (e.g. "#3164a3") to render each cell as a small rounded color square instead of text. This is useful for series-keyed tables — a "Series" or "Color" column where each row's swatch matches that row's color elsewhere on the board:

style:
  columns:
    kind:
      label: Color
      swatch: true

The column's underlying data must already be CSS color strings; swatch only changes how the cell renders, not the query.

Auto-sizing: compact vs text columns¶

The table auto-sizer classifies each column as compact or text based on its measured content demand:

Compact columns (demand ≤ 220px, or spark columns) are pinned to their measured demand. Short enums, numbers, dates, and short strings are compact by default.
Text columns (demand > 220px) compete proportionally for the remaining budget after compact columns are pinned.

This means a freeform notes or description column no longer squashes every compact column down to unreadably narrow widths. The compact columns keep their natural size; the text column gets whatever is left.

When compact columns' total demand exceeds the available width the table accepts overflow (horizontal scroll) rather than squishing — clipping is honest, mid-word wrapping is not.

`max_width:` — capping a text column¶

Use max_width: on a text column to prevent it from growing beyond a ceiling even when there is spare budget:

style:
  columns:
    csm_name: {}
    account: {}
    arr:
      format: "$,.0f"
    next_steps:
      max_width: 400   # cap the freeform text column; compact columns absorb the remainder

max_width: accepts an integer (pixels) or a CSS-style percentage string ("30%"). It is mutually exclusive with width: — setting both raises a validation error at compile time.

When a text column is capped below its natural budget share, the leftover budget is redistributed to the compact columns proportionally, so the table always fills its tile.

Inline spark configs support small in-cell visual encodings: line, area, bar (single horizontal bar, absolute magnitude), bar-normalize (single horizontal bar scaled to a ceiling, with background track), and columns (multi-value vertical bars).

Number Formatting¶

Numeric columns with no explicit format: are formatted at render time using the engine-predefined number_default format, so large numbers read compactly instead of at full precision. number_default uses .3~s (three significant figures with an SI magnitude suffix and trailing-zero trim), which renders 452342060.87 as 452 M, 20640228.74 as 20.6 M, and a fraction like 0.671 as 671m.

When a column's values share one common magnitude — most rows land in the millions, say — the column declares that magnitude once instead of repeating it on every row: the top (or summary) row shows the suffix and the rest show bare, digit-aligned numbers at the same scale, the same way a chart axis shows one magnitude label for its whole tick ladder. A column whose values span very different magnitudes, or that doesn't compact at all, keeps today's per-row formatting.

To show a column at full precision, or in any other style, set format: on that column entry with a d3 numeric spec (or a predefined name such as number for plain comma-grouped decimals):

style:
  columns:
    arr:
      format: "$,.0f"   # "$452,342,061" — explicit format overrides the SI default
    order_id:
      format: number    # predefined name — plain comma-grouped decimals

An explicit column format: always wins over the default.

Date and Datetime Formatting¶

Date and datetime values from the warehouse (DATE, TIMESTAMP, TIMESTAMPTZ columns) are formatted at render time using the engine-predefined date_short format — no SQL-side strftime is required. date_short renders 2024-05-19 as 19 May 2024.

To override the format for a specific column, set format: on that column entry using a strftime-style spec beginning with %:

style:
  columns:
    event_date:
      label: "Event Date"
      format: "%B %d, %Y"   # "May 19, 2024"

Assigning a non-strftime format spec (such as a d3 numeric format like ",.0f") to a date column raises an error at render time — use a %-prefixed strftime spec or omit format: to use the predefined date_short format.

Date columns are right-aligned and excluded from text-wrap layout automatically. Timezone-aware datetimes are converted to UTC before the date component is extracted, so the displayed date is always consistent regardless of the server's local timezone.

KPI Charts¶

Use type: kpi when the output is fundamentally one important value rather than a plotted series.

Minimum Required for a KPI¶

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`query`	KPI data row	Query name or query reference	Supplies the dataset.
`type: kpi`	KPI renderer	Literal `kpi`	Selects the KPI renderer.
`value`	KPI value binding	Column reference (string column name)	Chooses the value to display.

format is especially important for KPIs because it controls how that single value is rendered.

Callout Charts¶

Use type: callout for a bordered message card inside a dashboard tile. Callouts do not run queries — they are static content with semantic coloring driven by style.tone:.

Runtime chart failures (query errors, data-shape mismatches, render failures) also render as callout cards with explicit tone: negative, using the same renderer and style.charts.callout structure defaults.

Minimum Required for a Callout¶

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`type: callout`	Callout renderer	Literal `callout`	Selects the callout renderer.
`message`	Body text	String	Required. Wraps inside the tile width.
`title`	Heading	String	Optional heading above `message`.
`style.tone`	Palette role	`info`, `positive`, `negative`, `warning`	Optional. Defaults to `info`.

charts:
  migration_warning:
    type: callout
    title: Migration warning
    message: >
      Two tiles could not be migrated automatically. Review the source
      dashboard before publishing.
    style:
      tone: warning

rows:
  - migration_warning

Theme defaults live under style.charts.callout (padding, border, title/message typography). Per-chart style.tone: selects which palette role supplies background, border, and text colors (info.*, positive.*, negative.*, or warning.*).

Spark Bar Charts¶

type: spark_bar is a compact ranked text-plus-bar chart used by inspector-style summaries. For authored dashboards, prefer a table with an inline spark column (spark.type: bar or spark.type: bar-normalize) when you need custom column order, formatting, row styling, or conditional formatting.

When you do use type: spark_bar, the data fields are x for the label column and y for the value column. label: and value: are not accepted on spark_bar charts.

charts:
  owners_ranked:
    type: spark_bar
    query: owner_counts
    x: owner
    y: objects

Spark-Bar Style¶

dbt charts field	Maps to renderer behavior	Allowed values	Notes
`style.max_bars`	row cap	Integer	Maximum number of visible rows before truncation.
`style.spark_bar.label.visible`	left label visibility	`true` or `false`	Set `false` to hide labels beside the bars (default: `true`).
`style.spark_bar.count.visible`	right count visibility	`true` or `false`	Set `false` to hide right-side numeric counts (default: `true`).
`style.spark_bar.bar.height`	row/bar height	Integer	Controls compactness of the display.
`style.spark_bar.bar.color`	bar fill color	Color value	Spark-bar paint surface.
`style.spark_bar.bar.background`	bar track color	Color value	Spark-bar background/track paint surface.