Visual cues at a glance
A quick reference table covering every visual signal in the diagram. Bookmark this if you're skimming. For the explanations behind each cue, follow the link in the rightmost column.
Containers
| What you see | What it means | More |
|---|---|---|
| Dashed-border box around entities | A container declaration (Schema, Database, Container, etc.) | Containers |
| Colored header band on the container | Identifies the container by its accent color | Containers |
| Keyword and name in the header | The container's keyword (Schema, Database, etc.) and its name | Containers |
→ EngineName on the right of the header | The target storage engine (Oracle, MongoDB, etc.) | Containers |
| All entities inside share a header color | They belong to the same container | Containers |
| Thicker blue outline on the container | The container is currently selected | Inspector pane |
Entity cards
| What you see | What it means | More |
|---|---|---|
| Card with header band and field rows | An entity (Table, Entity, Collection, Record) | Entity cards |
| Keyword in the header (small text) | "Table", "Entity", "Collection", or "Record" | Entity cards |
| Entity name in the header (large text) | The entity's declared name | Entity cards |
| Thicker blue card outline | The entity (or one of its fields) is currently selected | Inspector pane |
| Light blue row background | That field row is selected | Inspector pane |
| Blue strip on the left edge of a row | Selection accent on the selected field row | Inspector pane |
Field badges
| Badge | Color | What it means | Source |
|---|---|---|---|
| P | Yellow circle | Primary key | [pk] or [primary key], or a pk line in constraints { } |
| U | Purple circle | Unique key on this field alone (not shown on a primary key) | [unique], or a one-field unique line in constraints { } |
| U1, U2 | Purple pill | Member of a composite unique key; fields with the same number form one key | A unique line on several fields in constraints { }, numbered in declaration order |
| ! | Red circle | Not nullable | [not null] or [required] |
| fk | Cyan pill | Child side of a foreign key | computed from the Refs |
| dk | Dark cyan pill | Parent side of a foreign key | computed from the Refs |
| fm | Teal pill | Child side of a foreign master | computed from the Refs |
| dm | Dark teal pill | Parent side of a foreign master | computed from the Refs |
The four relationship markers are never written by hand: the diagram derives them from the relationships. A field that parents both kinds shows dk and dm side by side.
Composite primary keys show the PK badge on every member field, not just the first one. A composite unique key shows a numbered badge on each of its fields, U1 for the first composite unique key of the entity, U2 for the second, so the fields of one key read together; no single field is unique on its own, which is why the plain U does not appear. The badge shows on primary key fields too, next to P. The entity's inspector lists each key with its name under Constraints. A composite unique entry in indexes declares an index, not a key, and shows no badge. In a document declaring xdbml: 0.6, primary key fields also show the required marker, because a primary key field is never null.
Field row text
| What you see | What it means |
|---|---|
| Plain field name | A user-defined field |
| Italic field name | A synthetic row ([item], {alt}, <key>, <value>, <item>, [N]) that doesn't correspond to a user-written field |
| Type label right-aligned | The compact form of the field's type |
varchar(100), decimal(10,2) | A sized scalar type with parameters |
object {…} | An object type with sub-fields rendered as nested rows |
array of X | An array type; X is the element type's short form |
oneOf (n), anyOf (n), allOf (n) | A polymorphism with n alternatives |
map [K → V] | A map type from K to V |
set [X] | A set of X |
tuple (n) | A tuple with n positions |
Disclosure carets
| Caret | Meaning |
|---|---|
▾ (downward) | The parent row is expanded; children are visible. Click to collapse. |
▸ (rightward) | The parent row is collapsed; children are hidden. Click to expand. |
| No caret | Leaf field; no children to show. |
Carets only appear on rows whose field has structured-type children. See Nested fields.
Relationships
A line between two entities is a Ref:. Its style gives the relationship type:
| Line | Meaning |
|---|---|
| Solid | Foreign key (referential) |
| Dotted | Foreign master (denormalized replication) |
| Small open circles | Inactive relationship, of either kind |
| Line to a card edge, small filled triangle | Conceptual relationship between entities, reading toward the triangle |
Each endpoint carries a symbol indicating cardinality and optionality:
| Symbol | Cardinality | Reads as |
|---|---|---|
─║ | Exactly one | min=1, max=1 (mandatory, single) |
─○║ | Zero or one | min=0, max=1 (optional, exclusive) |
─≺ | One or many | min=1, max=* (mandatory, multiple) |
─○≺ | Zero or many | min=0, max=* (optional, multiple) |
The ring (○) means "zero allowed." The bar (║) caps "exactly one." The crow's foot (≺) means "many," with the V opening toward the entity. See Relationships & crow's foot notation.
When the line is blue and thicker, the relationship is currently selected.
A range that a source: or target: setting states also shows as a text label beside its glyph, such as 2..5, which a glyph can only approximate. A ring at the parent end of a foreign key that may hold null, or at the end a ? marks, shows that end is optional.
With Display > Relationship names on, a named Ref shows its name in italics at the middle of its line.
Sticky notes
| What you see | What it means |
|---|---|
| Box with a folded corner, its text formatted | A sticky note, a named top-level Note, its text Markdown |
| Light yellow box | The default color; a color setting gives another |
| Text with no box | color: none |
| Note inside a Container frame | A sticky note of that Container, which carries it when dragged |
See Sticky notes.
Data lineage
A curve with an arrowhead is a Dep: the element at the arrowhead is computed from the element at the other end, by a job or a query outside the model (spec §27). It carries no cardinality symbol, so it never reads as a relationship, whose lines turn at right angles.
| What you see | What it means |
|---|---|
| Amber curve, arrowhead at one end | A dependency, from upstream to downstream |
| Curve ending at a field row | The dependency names that field |
| Curve ending at a card's header | The dependency names the entity or the View |
| Several curves meeting at a dot before one arrowhead | Fields of one Dep combined into one, such as a first and a last name into a full name |
| A curve in another color | The color of the Dep, or of that one dependency |
| Dashed curve | An indirect kind of transformation: a join, a lookup, a filter, a grouping or a condition |
| A pill on a curve | The kind of transformation; a dashed border for an indirect kind |
With Display > Relationship names on, a named Dep shows its name at its junction, or along its curve. Clicking a curve selects the Dep: its curves and arrowheads turn blue, the rows of the fields at its ends take the selection tint, and an entity or a View it names with no field is outlined. The inspector reads its dependencies back as sentences that name the elements, such as "fct_orders.revenue is computed from stg_orders.revenue", and shows its note and its settings.
An automatic arrangement places each entity to the right of the entities it is computed from, where the layout allows. See Data lineage.
Supertype groups
| What you see | What it means |
|---|---|
| Half-circle below an entity, lines to entities below it | A supertype group: the entity above is the supertype, the entities below are its subtypes |
| Cross inside the half-circle | exclusivity: disjoint: at most one subtype per instance |
| Bar just above the base | completeness: total: every instance is at least one subtype |
| Dashed cross or bar | That setting is not stated |
| Several half-circles on one entity | One group per axis of specialization |
See Supertype groups.
Colors
| Color | Where it appears | What it means |
|---|---|---|
Blue (#2563eb) | Selection outlines, accents | Currently selected element |
| Yellow | P badge | Primary key |
| Purple | U badge | Unique constraint |
| Cyan, teal | fk, dk, fm, dm badges | Relationship roles of a field |
| Red | ! badge, error squiggles, diagnostics errors | Required field, or an error |
| Amber | Warning indicators, screenshot placeholders in help | Warning or todo |
| Grey | Type labels, cardinality text, indent guides | Subordinate information |
| Container accent colors | Container header bands, member entity header bands | Container identity (deterministic from name) |
Cursor states
| Cursor | Where | What it indicates |
|---|---|---|
| Default (arrow) | Empty canvas | Click to inspect the diagram on display |
| Pointer (hand) | Anywhere clickable: entity headers, field rows, container bodies, relationship lines, supertype group symbols, sticky notes, dependency curves | Clickable to select |
| Grab / grabbing | Entity header band when held | Drag in progress |
| Col-resize | Pane dividers | Drag to resize the pane |
What's next
If you want the explanations behind the cues: