Focus and filter

Real applications have dozens or hundreds of tables. Rendering all of them at once is possible (Truss raises Mermaid’s size guards so large schemas draw rather than error), but it is rarely what you want to read. Focus and filter are how you keep things legible.

Filter

Type in the Filter box to narrow the diagram to tables whose name contains what you typed. It is a plain, case-insensitive substring match on the table name. Clearing the box shows everything again.

Focus

Pick a table in Focus to reduce the diagram to that table plus its foreign-key neighbours. Neighbours are followed in both directions: tables the focused table references, and tables that reference it.

• The focused table is centred in the viewport and highlighted with an accent border, so you can always find it.
• Depth controls how many hops of neighbours are shown. Depth 1 (the default, configurable via focus.default_depth) shows immediate neighbours; increase it to pull in neighbours-of-neighbours.

Searching for a table

From v1.9.0 the Focus control is a searchable picker: type part of a table name and the list narrows as you type.

• It matches anywhere in the name, case-insensitively, so item finds order_items as well as items. This is the same substring rule the Filter box uses, so the two controls agree.
• Matches are ranked: an exact name first, then names that start with what you typed, then names that contain it further in. Typing item still puts items at the top.
• The part that matched is marked in each row, so it is clear why a table is in the list.
• Leaving the box empty lists every table, with Clear focus as the first row.
• The match is literal text, not a pattern: a . means a dot.

The picker is fully operable from the keyboard. Arrow keys move through the list, Home and End jump to its ends, Enter commits the highlighted table, Escape closes the list and puts back the table you had focused, and Tab moves on without committing a half-typed name. Screen readers hear the number of matches as you type. See Accessibility.

Typing a name that does not exist focuses nothing: the box reverts when you leave it, rather than quietly focusing the wrong table.

Focus and filter compose: focus operates on whatever the filter left in, so you can filter to a group of tables and then focus within it.

You can also click a table name in the diagram to focus it directly, without using the Focus box. The same menu lets you export that table’s structure; see Exporting a table.

Shareable views

The current connection, filter, focus, and depth are reflected in the URL query string, updated live as you interact. So /truss?focus=projects opens straight into that focused view, and you can bookmark or share any view you have set up. Nothing is stored server-side; the query string is the whole state.

Auto-fit and the readable floor

Whenever the content changes (on load, filter, focus, or connection switch) the diagram auto-fits the viewport. The auto-fit honours a readable floor (diagram.min_zoom, default 0.7): a large schema is framed at a legible zoom that you pan around, rather than shrunk to an unreadable speck.

The Fit button ignores the floor and frames the whole diagram at once, so the full overview is always one click away.

Large-schema hint

Above a configurable table count (large_schema.warn_above, default 60), an unfocused, unfiltered diagram shows a hint suggesting you filter or focus. It is only a hint; the diagram still renders.

Excluded tables

Framework and infrastructure tables (migrations, sessions, cache, jobs, and so on) are excluded by default via excluded_tables. Exclusions are applied server-side, so excluded tables never reach the browser at all. See the Configuration reference.