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.
External links¶
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-ALIASindct validateanddct serve. - Each alias must be unique across the project: when two boards claim the same
alias, both fail with
ERR-BOARD-ALIASand 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 rundct validaterather 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.
Board link settings¶
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:
- The link's own
open:(link: {url, open}on a chart, column, orheader_link:). - The root board's
links.open. 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
EMEAsegment of theenterprisebar addsregion=EMEAandplan=enterprise. - A chart whose only dimension is a foreign key links to the referenced table's detail page instead of a filtered list.
- An
xchannel 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.