Skip to content

Linking Between Boards

Connect boards with Markdown links or chart link: fields. dbt Charts rewrites both at render time so the same YAML works in both dct serve and Cloud.

This page covers how link paths resolve, URL aliases, and the board-wide links: settings. For what links let you build (drill-downs, click-to-filter, modal detail views), start with Links and Drill-Downs.

Drill down from charts and tables

Charts and tables support a link: field that turns each data element into a clickable link: navigating to another board or updating a variable in-place. Board-root paths are resolved the same way as Markdown links.

charts:
  tickets_by_status:
    type: bar
    query: tickets
    x: status
    y: count
    link: "/zendesk/tickets/list?status={{ x }}"   # {{ x }} = clicked bar's status

For tables, link: can be set at the chart root (applied to every cell) or overridden per column in style.columns:

charts:
  tickets_table:
    type: table
    query: open_tickets
    link: "/zendesk/tickets/detail?id={{ ticket_id }}"   # default for all cells
    style:
      columns:
        status:
          link: "/zendesk/backlog/?status={{ status }}"  # overrides root for this column
        ticket_id:
          visible: false   # feeds the row link only; never a display column

See Chart Interactions for the full link: reference.

Root-relative paths

Paths start with / and are relative to the dashboard namespace root; not the file system. You never type a storage prefix like charts/.

text: |
  [Open tickets](/zendesk/tickets/list?status=open)
  [Ticket detail](/zendesk/tickets/detail?id={{ ticket_id }})

/zendesk/tickets/list resolves to the board stored at charts/zendesk/tickets/list.yml (same path in Cloud; both use charts/).

Validation warns about any link to a board the project does not have, and suggests the slug when the path ends in one.

Relative paths

../ and ./ resolve against the current board's directory.

If you are on zendesk/tickets/list:

Link Resolves to
./detail zendesk/tickets/detail
../overview zendesk/overview
text: |
  [Detail view](./detail?id={{ ticket_id }})
  [Back to overview](../overview)

Package authors should use sibling-relative links such as ./backlog between boards in the same directory. The same link works when the package's boards are served from zendesk/overview and when the package repository itself is opened with overview at the root. A rooted /zendesk/backlog link requires the boards to stay under zendesk/.

Query parameters and variables

Query strings on links map directly to dashboard variables. This is how you pass context between boards:

text: |
  [See ticket](/zendesk/tickets/detail?id={{ ticket_id }}&status={{ status }})

Suffix stripping

You can optionally include .md, .yml, or .yaml suffixes; dbt Charts strips them automatically:

text: |
  [Tickets](/zendesk/tickets/list.md)

resolves identically to /zendesk/tickets/list.

Links starting with http://, https://, mailto:, or # are never rewritten and pass through unchanged.

In dbt Charts Platform, board links also inherit the current branch scope.

URL aliases & parameterized routes

aliases: is a root-level list of absolute URL paths that 302-redirect to this board's canonical file-path URL. Each entry must start with /; trailing slashes are normalized automatically.

aliases:
  - /old-reports/
  - /legacy/sales/

Rules:

  • Every alias must be absolute: it starts with a leading /. A relative entry fails validation on that board.
  • An alias must not collide with a real board file path; the board claiming it fails with ERR-BOARD-ALIAS in dct validate and dct serve.
  • Each alias must be unique across the project: when two boards claim the same alias, both fail with ERR-BOARD-ALIAS and the alias redirects nowhere until all but one drop it. Every other board keeps serving. dbt Charts Platform does not report the collision; there a duplicate resolves to the first board by slug, so run dct validate rather than relying on it.

Parameterized aliases

An alias may contain a <name> capture segment. A request matching the pattern 302-redirects to the board's canonical URL with the captured segment appended as a query parameter of the same name, which the board then reads as a variable. This gives a single detail board a clean per-entity URL:

# charts/milestone.yml  (canonical URL: /milestone)
aliases:
  - /milestones/<name>
variables:
  name:
    input: select
    options:
      query: milestone_options
      column: slug

/milestones/m3-public-launch redirects to /milestone/?name=m3-public-launch, and milestone.yml renders with name bound to m3-public-launch.

  • A capture name matches exactly one non-empty path segment (no /). Use a capture name that matches the variable you want it to fill.
  • A real board file always wins over a pattern alias, so /milestones/ (a list board) and /milestones/<name> (the detail redirect) coexist without conflict.
  • Plain aliases (no <name>) redirect as before; only aliases with a capture are treated as patterns.

Aliasing a data or inspector route

The /data/... and /inspector/... paths are reserved for the built-in schema browser. An aliases: entry can still claim one of these paths: the alias redirect takes precedence over the generated system route, letting a board override what that URL serves.

# charts/warehouse_orders.yml
aliases:
  - /data/warehouse/public/orders

dbt Charts Platform offers a Make this a board button that does this for you from a generated /data/ or /inspector/ view.

The links: block sets link defaults for the whole page. Only the root board (or charts/meta.yml) sets it: a nested board that authors links: is an error (ERR-LINKS-NESTED), and nested boards take the root's.

Both keys default to the values the comments name; write one only to change it.

links:
  auto: true      # default false; true adds data-page links to table rows and chart marks
  open: modal     # default page; one of page | modal | preview | new_tab

How a link opens, first match wins:

  1. The link's own open: (link: {url, open} on a chart, column, or header_link:).
  2. The root board's links.open.
  3. page.

These always open as a page, whatever links.open says: a ?variable= link (it updates the board in place), the ?column=value filter link on a table cell, an email or url column's implied link, a KPI's implied link, and a custom chart's per-row link (the template draws its own anchor).

links.auto replaces the old board key auto_link: true. Boards that still write auto_link are migrated automatically. A nested board's auto_link migrates to a nested links:, which is an error: move it to the root board.

See Opening a link in a modal, preview, or new tab for what each open: does.

Auto-linking tables and charts

Set links.auto: true at the board root to link charts to the built-in data pages without writing a link: on each one. It applies to every chart that sets no link: of its own. Automatic links open by links.open.

links:
  auto: true

charts:
  orders_table:
    type: table
    query: orders
  orders_by_status:
    type: bar
    query: orders_by_status
    x: status
    y: order_count
  totals_table:
    type: table
    query: totals
    link: false      # this one stays unlinked

Default is off. Explicit link: on a chart or column always wins over links.auto; set link: false on a chart to suppress its automatic link without disabling links.auto board-wide.

Table rows

Each row links to the canonical detail page for its record: /data/<source>/<schema>/<table>/detail/?<key>=<value>. A table gets this link only when its query returns one row per record from a single base table; an aggregated table gets none. A column that is a foreign key (declared with a dbt relationships test) also links its cells to the referenced table's detail page. An explicit link: on a column wins over that foreign key link.

Chart marks (drill-down)

Clicking a bar, point, area, or slice opens the table's data page filtered to the rows behind that mark: /data/<source>/<schema>/<table>/?<column>=<value>. In the example above, clicking the shipped bar of orders_by_status opens the orders data page filtered to status=shipped. The same drill-down works with links.open: modal or preview, which show the data page without leaving the board.

The link is built from the chart's dimension channels, x and color:

  • A chart with both filters by both: clicking the EMEA segment of the enterprise bar adds region=EMEA and plan=enterprise.
  • A chart whose only dimension is a foreign key links to the referenced table's detail page instead of a filtered list.
  • An x channel whose values are decimal numbers is treated as a measure and skipped. A chart with no other dimension gets no link.

A chart gets no automatic link when its query does not resolve to a single base table (for example a join), when the chart type has no x or color channel (KPI and callout charts), or when none of its dimension columns exist on the base table. These charts stay unlinked rather than guessing a target. Write a link: to drill them somewhere specific; see Drill-Down Links.

List / detail convention

Teams can standardize recognizable path segments for common board roles:

  • …/list: filtered overview or table
  • …/detail: single-entity board (variables in query, for example, ?id=)

This is a naming convention, not enforced by dbt Charts.