Give your data a semantic model — Unity Intelligence

A semantic model gives Unity the structure and meaning of a connection's data. It describes queryable entities, their fields, relationships between them, and reusable data definitions such as calculated columns and measures.

The assistant uses this model to discover exact identifiers and construct queries. The model also participates in query compilation, lineage, and relationship-based filtering.

Configure a model

Open Data, select the connection, and open Model Builder.
Use Select Tables From Database to choose the source tables you want to expose.
In Data, select an entity and review its name, columns, and Entity SQL.
Open Relationships to review or create the links between entities.
Open Data Definitions to add reusable fields or measures.
Click Save Changes. Save definition edits before validating the persisted model.

A connection model can be used by multiple reports. Treat a change to an existing shared measure as a change to the meaning of those reports, not just the current page.

Model objects

Object	Purpose
Entity	A logical table exposed to queries. It can be backed by a selected table or read-only entity SQL.
Field	A column with a model identity, name, type, and source information.
Relationship	A link between fields in two entities, with cardinality, active state, and origin.
Direct column definition	A reusable reference to an existing field.
Derived column definition	A row-level expression calculated from backing fields.
Measure	A reusable analytical expression, often an aggregate.

Display names, logical entity identifiers, and physical database names are not always identical. Inspect the catalogue or entity details before copying a name into SQL.

Edit entities

In Data, choose an entity card to inspect its SQL. You can rename the entity and edit the read-only query that exposes its fields.

Entity SQL can express a useful source view without changing the underlying database tables. Its output determines which columns downstream definitions and visuals can reference. Removing or renaming an output column can affect dependent calculations and filters.

Use explicit columns and stable aliases for important fields. Preserve source key columns when you need unambiguous row selection in detail tables.

Define relationships

In Relationships, click one column and then another, or drag a column onto its counterpart. Select a relationship to edit From, To, Cardinality, and Active.

The diagram supports moving entity cards, zooming, and resetting the view. Relationship records distinguish database constraints, detected links, and user-authored links.

Cardinality	Meaning
1:1	One matching row on each side.
1:Many	One row on the first side can match several on the second.
Many:1	Several rows on the first side can match one on the second.
Many:Many	Multiple matching rows can exist on both sides.

Active relationships pass filters in both directions. Cardinality describes matching rows; it does not select a filter direction. The editor reports conflicting paths when runtime filtering cannot choose a deterministic route.

A relationship does not automatically make every SQL join or aggregate correct. Check row grain and duplicate expansion, especially across one-to-many or many-to-many joins.

Create a reusable calculation

In Data Definitions, set the Alias, Type, Owning entity, Output type, Backing fields, and SQL Expression. Add a description that explains the business meaning.

For an illustrative orders entity:

Definition	Type	Example expression
line_amount	Derived Column	`quantity * unit_price`
revenue	Measure	`SUM(amount)`
order_count	Measure	`COUNT(*)`

Use fields that exist in your model and expressions supported by the source dialect. Define whether revenue includes tax, refunds, discounts, and currency conversion; the expression alone may not answer those questions.

Inspect the current model definitions and their usage. Add a reusable
net revenue measure only if an equivalent definition does not exist.
Use the documented refund and discount fields, explain the expression,
and validate it before using it on the report.

Definitions carry version, scope, and validation information. Inspect usage before changing an alias, expression, output type, or owning entity.

Understand compilation and lineage

A visual's authored SQL expresses the analytical query. Unity expands applicable entity SQL and model definitions, resolves backing fields, and applies supported filters when preparing executable SQL.

Lineage connects an output field back to its model source. This supports filtering and helps distinguish a formatted label from an actual source key. Ambiguous or incomplete lineage can limit an interaction even if the displayed value looks correct.

See Query inspection to compare authored and executable SQL.

Choose the right place for meaning

Store reusable executable calculations in the model. Put report-specific terminology and conventions in Report instructions. Put supporting documents and templates in Report files.

Instructions and documents can guide the assistant, but they do not automatically become validated model expressions.

Troubleshoot a model

Problem	Check
A field cannot be found	Entity SQL output, exact logical identifier, and saved model state.
An aggregate is unexpectedly large	Join grain, duplicate rows, and relationship cardinality.
A cross-filter cannot be applied	Active relationships, conflicting paths, field lineage, and key completeness.
A definition no longer validates	Its backing fields, owning entity, output type, and source dialect.
A change affects another report	Shared connection-model usage and saved consumers of the definition.