Skip to main content

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.

Shop
Shoppublic.countries.code < public.users.country_codepublic.users.id < public.orders.user_idpublic.orders.id < public.order_items.order_idpublic.products.id < public.order_items.product_idpublic.merchants.id < public.products.merchant_idpublic.countries.code < public.merchants.country_codepublic.orders.id < public.payments.order_idpublic.orders.id < public.invoices.order_idusersusersid integer · primary keyidintegeremail varchar · unique · not nullemailUNNvarcharcountry_code char(2) · foreign keycountry_codechar(2)created_at timestampcreated_attimestampcountriescountriescode char(2) · primary keycodechar(2)name varcharnamevarcharordersordersid integer · primary keyidintegeruser_id integer · foreign keyuser_idintegerstatus varcharstatusvarcharcreated_at timestampcreated_attimestamporder_itemsorder_itemsorder_id integer · foreign keyorder_idintegerproduct_id integer · foreign keyproduct_idintegerquantity integerquantityintegerunit_price decimal(10,2)unit_pricedecimal(10,2)productsproductsid integer · primary keyidintegermerchant_id integer · foreign keymerchant_idintegername varcharnamevarcharprice decimal(10,2)pricedecimal(10,2)merchantsmerchantsid integer · primary keyidintegername varcharnamevarcharcountry_code char(2) · foreign keycountry_codechar(2)paymentspaymentsid integer · primary keyidintegerorder_id integer · foreign keyorder_idintegeramount decimal(10,2)amountdecimal(10,2)paid_at timestamppaid_attimestampinvoicesinvoicesid integer · primary keyidintegerorder_id integer · foreign keyorder_idintegernumber varchar · uniquenumberUvarchartagstagsid integer · primary keyidintegerlabel varcharlabelvarchar

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.

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.

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:

KeyExampleOpens the diagram…
viewview=salesin a DiagramView
tabletable=orderscentred on a table, lit with its relationships
hopstable=orders&hops=2focused on that table's neighbourhood (0 to 5 hops)
detaildetail=keysat a detail level: all, keys or names
vpvp=120,-40,0.8at an exact position and zoom (x, y, zoom)
qq=pricewith the search panel open on that query
pathpath=users~productswith 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.

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:

  1. the id you give: id="billing" on a fence, id="billing" on the component;
  2. diagram- and the title as a heading slug: title="Shop" gives #diagram-shop (the prefix keeps it apart from a ## Shop heading on the same page, whose anchor is #shop);
  3. 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.

Links with keys and the broken-anchor check

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):

KeysAction
/, Ctrl/Cmd+KSearch
TabMove to the toolbar, then from table to table
← → Home EndMove between toolbar buttons
Enter / SpaceOpen or close the focused table's card
EscClose a menu, the card or search; clear the highlight; leave focus mode, one step per press