Exploring diagrams
Every diagram on this site — and in your docs with the plugin — is more than a picture. You can search it, light up how two tables are related, hide columns, focus on the neighbourhood of one table, and share a link that opens it exactly where you are. Everything has a keyboard path.
Search
Press the magnifier in the toolbar, or / or Ctrl/Cmd+K with the diagram focused. Search finds tables, columns, enums, table groups, sticky notes and views as you type, and tones the matches while dimming the rest. Use the arrow keys to move through the results and Enter to pick one: the diagram moves to that table and lights it and its relationships (a column lights its row too). Esc closes the panel.
Try it: search the shop diagram for “price”.
Relationship path
Switch the search panel to Path and choose two tables. relvista finds the shortest chain of foreign keys between them, lights the tables and refs on it, fits it on screen, and lists the hops ("users → countries → merchants → products, 3 refs"). When several chains are equally short, it takes the one through the tables declared first. Two tables with no chain of refs between them say so ("No relationship path between users and tags").
Try it: the path from users to products, or users and tags, which are not related.
Detail level
The Detail level menu (the rows icon) shows All columns, only Keys (primary and foreign keys, the columns refs attach to) or table Names only. Large schemas read best as names first; the layout does not move when you switch.
To start a diagram at another level, add detail=keys (or names) to a fence, pass
detailLevel="keys" to the component, or set themeConfig.dbml.detailLevel for the whole site.
Try the shop diagram with names only.
Focus on related tables
Click a table (or Tab to it and press Enter) to open its card, then Show related: only the tables within one ref of it stay, pulled in around it (each keeps its direction from the table, so the picture still looks like the diagram) and fitted on screen; the saved positions do not change, and tables cannot be dragged until you leave. The chip at the top ("Related to orders · 1 hop") has − and + to widen or narrow the circle (up to 5 hops) and ✕ to leave; Esc leaves too.
Try orders and its neighbours.
Deep links
Every diagram has an anchor, the id of its box on the page: #shop scrolls to the diagram
above, like a heading link. After the anchor, a link can say what the diagram should show:
| Key | Example | Opens the diagram… |
|---|---|---|
view | view=sales | in a DiagramView |
table | table=orders | centred on a table, lit with its relationships |
hops | table=orders&hops=2 | focused on that table's neighbourhood (0 to 5 hops) |
detail | detail=keys | at a detail level: all, keys or names |
vp | vp=120,-40,0.8 | at an exact position and zoom (x, y, zoom) |
q | q=price | with the search panel open on that query |
path | path=users~products | with the relationship path between two tables lit |
Keys combine: #shop&view=sales&table=orders
opens the sales view centred on orders. Tables are written as in the DBML (orders,
billing.invoices, or an alias); invalid values are ignored rather than breaking the page. Links
work from other pages too: /docs/exploring#shop&table=payments.
Copying a link
The toolbar's link button (Copy link to this diagram) copies a link to the diagram as you see it — its view, the table you picked, focus, detail level, search or path, and the position — and says “Link copied”. From then on, and whenever the page was opened with a link to that diagram, the address bar follows what you do in it, without adding history entries, so the browser's address is always a link back. Other diagrams on the page never change the address, and links to headings work as usual.
Choosing the anchor
The anchor is, in order:
- the
idyou give:id="billing"on a fence,id="billing"on the component; diagram-and the title as a heading slug:title="Shop"gives#diagram-shop(the prefix keeps it apart from a## Shopheading on the same page, whose anchor is#shop);- otherwise
diagram-and 8 hex digits computed from the DBML and the view, which stays the same from build to build as long as the diagram does not change.
Give an id when you link to a diagram from elsewhere, or when two diagrams on a page share a
title: the build warns when two diagrams on one page end up with the same anchor, and the
browser console when a diagram's anchor is also the id of another element. Anchors are registered with Docusaurus' broken-link check, so [the shop](#shop) passes it.
Docusaurus reads everything after # as the anchor, so with onBrokenAnchors: 'throw' a Markdown
link such as [orders](#shop&table=orders) fails the build. Write those links as
<a href="#shop&table=orders" data-noBrokenLinkCheck>orders</a>, as this page does.
In the editor
The editor reads the same keys from its own address
(/editor/#view=sales&table=orders), keeps them up to date while you work, and its
Share dialog can include the position. The Open in editor button of a docs diagram carries
the current view and table along with the DBML.
Keyboard
With the diagram focused (click it, or Tab to it):
| Keys | Action |
|---|---|
| /, Ctrl/Cmd+K | Search |
| Tab | Move to the toolbar, then from table to table |
| ← → Home End | Move between toolbar buttons |
| Enter / Space | Open or close the focused table's card |
| Esc | Close a menu, the card or search; clear the highlight; leave focus mode, one step per press |