Give your data a semantic model

A semantic model gives Unity the structure and meaning of a report's data. Each report owns one model across its attached connections. 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

1. Open Data and click New query. To add a database that is not attached yet, use Get Data in the ribbon; it opens New connection on the same tab.
2. Choose the source. From tables adds one query per selected table, named as a copy if the report already has its name (customers (2)); it doesn't add relationships. Switch to SQL query to write a source query instead.
3. Review each query's name, output fields, and SQL, run the preview, and click Save query.
4. Open Relationships to review or create the links between queries, or ask the assistant to create them.
5. Open a query's Definitions to add reusable calculated columns or measures.

Reusing a connection does not share mutable model definitions between reports. A saved measure change affects its consumers throughout this report. Source queries use the connector's native dialect; calculations against report entities use DuckDB SQL.

Query edits are private drafts until Save query. Switching queries, closing the editor, or reloading the same browser tab keeps the draft; Discard resets it. The assistant can prepare a draft or, when asked to change the saved model, save directly through a separate model operation. Draft proposals and saved-model changes have different activity receipts.

Model objects

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 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 an output column, or removing or renaming a definition, keeps the model working: a rename is made in the calculations that name it, and Unity first lists any calculated column or measure that would no longer work, with the charts and filters that read them. Confirm, and those calculations are removed with the change; the charts and filters then show an error.

To rename a column and keep what uses it, choose Rename in its ⋮ menu in the Data panel, or ask the assistant. Unity selects the column under the new name in its table's query ("units" AS "quantity"), and charts, filters, relationships and the calculations that name it follow. Changing the name by editing the query yourself makes a new column instead. Analysis Services and API tables have no query to change, so their columns don't offer Rename.

Remove from model asks once before it removes a column: plainly when nothing uses it, or with a list of what is removed with it and what will show an error.

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, Active, and Cross-filter direction.

The diagram supports moving entity cards, zooming, and resetting the view. Unity never creates relationships on its own: you or the assistant add each one. The assistant can read the foreign keys your database declares.

Every relationship is many-to-one, as Power BI's default: its to end is the key end, and each value appears there once. Unity checks this when a relationship is added, its ends change, or it is made active again, and when a save changes the query of a relationship's to table: a to column with a repeated value or a blank is refused, as in Power BI (text compares as joins do, so A and a count as one value). Swap the ends if the other column is unique, or relate to a calculated table of the column's distinct non-blank values. The diagram shows each relationship as *:1.

Active relationships pass filters in their cross-filter direction, as in Power BI. Single, the default, passes a filter from the to (key) end to the from end only: a filter on products reaches order lines, and a filter on order lines doesn't reach products. Both passes filters each way. Saving Both is refused when it would give a filter a second path between two tables, as in Power BI. The editor reports conflicting paths when runtime filtering cannot choose a deterministic route.

Grouping by a table on a relationship's key (to) side never repeats rows: each row counts once in its group, and the groups add up to the total. Grouping the other way, such as a count of customers by an order column, counts a customer once in each group its orders fall in, so those groups can add up to more than the total. Report SQL you write yourself joins as written, so check its row grain.

A relationship change that would affect saved work asks first: adding, removing, activating or deactivating a relationship, or changing its direction, lists the charts that would show an error, the filters that would stop filtering, and the charts and filters that would read through another path and may show different numbers. Restoring a version lists the same in its warnings.

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:

Use fields that exist in your model and expressions admitted by Unity's report SQL contract. 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.

Add a typed measure

Some analysis can't be one SQL aggregate: a ratio of two measures from different tables, a share of the total, last year's value, a running total or a rank. Choose Typed measure as the definition type, then pick its kind and the fields it uses:

Typed measures are computed for each row of a visual at that row's grain, so totals and distinct counts stay exact. Report SQL can't read a typed measure; visuals and the assistant use them by field. Over Analysis Services, composites, shares and ranks of the model's measures work; time comparisons and running totals use the model's own DAX measures.

Format a measure

A calculated column or measure can carry a number format, as in Power BI: in its definition choose Format (Number, Percent or Currency), its decimals and whether to use a thousands separator. A percent says what its values are: ratios (0.372 shows as 37.2%) or percents already (37.2 shows as 37.2%). Currency is USD, EUR, GBP or JPY. Cards, tables, matrices, chart axes, tooltips and data labels then show the field in that format, unless the visual sets its own. A sum or count of a formatted column isn't formatted. Default removes the format. Report versions keep it, and restoring a version brings it back.

Without a format, a card or data label with automatic decimals shows up to two (620.5); with automatic display units, a scaled value keeps three significant digits (4.49M).

Add a calculated table

A calculated table is SQL over the report's tables whose outputs become fields, such as customers with their first order month. In Data, choose Add data → New calculated table, name it, write its SQL and Preview, then Save table. Saving runs the SQL once and takes its columns and types from that read.

A calculated table is listed with the other tables and marked Calculated. It is computed from all rows of the tables it reads: report, page and visual filters don't change its rows. Relate it to other tables to let filters reach it, and to let it carry filters to them. A table name can't change after saving; deleting a table that charts or pages read asks first, and so does an edit that removes a column a relationship uses.

Understand compilation

A visual stores a visual query that names model fields. Unity generates its SQL from the model: the tables' queries, calculated fields and measures, relationships and filters. See Query inspection to read a visual's fields and see its generated 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