Lineage, sample records, and notes

Model a transformation separately from a foreign key#

A relationship (Ref) expresses relational structure. A dependency (Dep) can express how one value is derived from another. In the modular shop, line-item values contribute to an order total:

Dep order_total [color: #c586c0] {
  billing.order_items.quantity -> purchase_order.total_amount
  billing.order_items.unit_price -> purchase_order.total_amount
  note: 'Aggregate line-item quantity and price into the order total'
  materialized: aggregate
}

Use upstream or downstream tracing to focus on dependencies of a table or column. Return to the unfiltered diagram after the investigation. A lineage-only view intentionally hides objects unrelated to the traced path.

The model documents a dependency; it does not implement the aggregation query or keep the total synchronized at runtime.

Add sample rows#

Use fictional records to make a schema easier to understand:

Table customers {
  id integer [pk]
  email varchar(320)
}
Records customers(id, email) {
  1, 'ada@example.test'
  2, 'linus@example.test'
}

Expand the table’s sample-record display in the diagram. Check that the records follow the declared column order and that values communicate the intended type. SQL import can retain supported INSERT data as sample records; choose deliberately whether that data belongs in source control or generated documentation.

Add context without adding columns#

Use notes and metadata for ownership and classification:

Metadata Table customers {
  owner: 'identity'
}
Metadata Column customers.email {
  classification: 'direct-identifier'
}

These annotations are documentation/model metadata, not new database fields. Rich notes appear in Markdown popovers and generated HTML/Markdown documentation. Keep operational descriptions close to the affected object so schema reviewers see them while navigating the diagram.

Custom properties can be displayed and filtered. When metadata is declared across files, inspect the effective values rather than assuming every declaration is additive.