Data models
A data model is Riff BI’s semantic layer: the tables from one connection, how they relate, and the measures and dimensions that dashboards are built from. Define a number once here, and every dashboard and every AI answer uses that definition.
Creating a data model
Section titled “Creating a data model”- Go to Data models and click New model.
- Name it and pick the connection it reads from.
- The model builder opens. Add tables, relate them, define fields, then publish.
Creators can see models and use Explore. Building and publishing them needs the Modeler or Admin role.
The model builder
Section titled “The model builder”| Area | What’s there |
|---|---|
| Sidebar → Model | The tables and relationships already in the model, the quality checks, and the model card. |
| Sidebar → Fields | Measures, time fields and dimensions, with search. |
| Sidebar → Context | Glossary terms, known pitfalls and golden queries: notes that help readers and the AI. |
| Sidebar → Warehouse | Every table the connection can see, ready to add. |
| Canvas | One card per table, with lines for relationships. Below it, a resizable preview of a table’s rows. |
| Right panel → Inspector | Settings for whatever you’ve selected. With nothing selected, it shows the model itself: name, description, counts and what needs attention. |
| Right panel → Rivo | The AI assistant. See Rivo. |
| Header | Explore, history, and Publish. |
Every change is saved to the model’s draft as you make it. Dashboards don’t see your changes until you publish.
Tables
Section titled “Tables”Adding tables
Section titled “Adding tables”- On the Warehouse tab, check a few tables and add them, or drag one onto the canvas.
- For data that needs reshaping first, click New SQL table on the Model tab. Write a read-only
SELECT(qualify tables with their schema), and every column it returns becomes a field. It is never created in the warehouse; the model reads it like a table.
Removing a table only removes it from the model. The warehouse table isn’t touched.
Table settings
Section titled “Table settings”Select a table to set it up in the inspector:
- Label: the name people see.
- Entity type: Fact (events or transactions, like orders), Dimension (things you group by, like customers), Bridge (links two tables many-to-many), Snapshot (a state captured over time) or Lookup (small code tables).
- Keys and grain: pick the columns that identify one row. Click Check against data to confirm no key repeats. A table’s grain shows as No grain, Guessed, Declared or Verified.
- Profiling: Profile all reads each column’s counts, ranges and common values, which helps Rivo and the quality checks.
Relationships
Section titled “Relationships”Relationships tell Riff BI how to join tables, so a chart can show revenue by customer region even though revenue and region live in different tables.
- On the canvas, drag from a column’s dot on one table to the matching column on another.
- In the inspector, check the join columns and set Cardinality: Many to one, One to many or One to one.
- Set the Join type: Left join keeps rows with no match; Inner join drops them.
- Click Create relationship.
- Suggestions: Riff BI suggests likely relationships from column names and data. Review one and click Add relationship.
- Many-to-many isn’t drawn directly: add a bridge table with a relationship to each side.
- Inactive relationships: when two tables can join in more than one way (an order’s order date and ship date both pointing at a calendar), add the extra path as inactive. A measure can then choose to Join through it.
Measures
Section titled “Measures”Measures are the numbers people ask for: revenue, orders, average order value. On the Fields tab, click New measure and pick its kind.
| Kind | Use it for | Options |
|---|---|---|
| Aggregate | Adding up or counting a column | Sum, Average, Median, Minimum, Maximum, Count, Count distinct. Only rows where adds conditions (e.g. only completed orders). |
| Formula | Combining measures | Write measures in [brackets]; type [ to pick one. E.g. [Revenue] / [Orders]. |
| Over time | Period comparisons and running totals | Year, quarter or month to date; a rolling window (e.g. last 7 days); previous period; same period last year. Show the value, the change or the % change. |
Each measure also has:
- Label and name: the label is what people read; the name is what formulas use. Renaming updates formulas that use it.
- Format: Automatic, Whole number, Two decimals, Currency (USD, EUR, GBP, INR, JPY, AUD, CAD, CHF) or Percentage. Where available, set decimal places and turn on Shorten large numbers (1.2M). A time measure with no format of its own follows its base measure; a percentage change is shown as a percentage.
- Certified: marks it as the trusted definition for dashboards and the AI.
- Context: a description, caveats, an owner, the date it’s usually shown over, and other names people use for it (“also called”). Readers and the AI both use these.
A preview under the definition shows the measure’s current value, so you can sanity-check it as you build.
Dimensions and time
Section titled “Dimensions and time”Dimensions are what you group and filter by: region, product, status. Every column of a model table is a dimension unless you hide it. Use Hide keys and technical columns to tidy the list for dashboard builders.
- Calculated dimensions: build one from a formula, e.g.
CASE WHEN [amount] > 100 THEN "large" ELSE "small" END. - Sort by: text sorts alphabetically, so months read April, August, December. In a field’s settings, set Sort by to another field of the same table (e.g. Month name sorted by Month) and every chart, table, filter list and Explore result shows it in that order. A preview under the control shows the order, and warns if one value pairs with two sort values. The numbers never show on the chart.
- Time fields: date columns can be grouped by year, quarter, month, week and day.
- Fiscal year: set the month your fiscal year starts in (Fields → Fiscal year starts in). Year-to-date measures then follow it.
- Value meanings: explain coded values (e.g.
Smeans Shipped) so readers and the AI understand them.
Context and quality
Section titled “Context and quality”The Context tab holds what a newcomer to your data would need to know:
- Glossary: business words a reader might not know, like GMV or churn, and the fields they mean.
- Known pitfalls: traps in the data, like “revenue is gross; refunds are separate”.
- Golden queries: questions with an answer you’ve checked in Explore. They show the AI what a correct answer looks like.
Also on this tab, per connection: whether assistants may read common values of non-personal columns. When it’s off, assistants see counts, not values (apart from the latest date in a table’s freshness column). See AI and your data.
The Model tab shows Quality checks (missing keys, unverified grain, unchecked golden queries and so on). Some only warn; others block publishing until fixed. After you publish, Model card summarises the model for readers and the AI.
Where a field comes from and what uses it
Section titled “Where a field comes from and what uses it”Select a measure, a dimension, a column, a table or a relationship. Its Lineage section answers two questions without leaving the inspector:
- Comes from: the column a measure adds up, the measures in a formula, the inputs of a calculated dimension.
- Used by: measures built on it, golden queries that ask about it, and every dashboard that uses it, with each chart and what it uses the field for (“Bar chart · the values”). A chart marked Broken names a field the model no longer has. Under a measure built on this one, a folded line such as Also, through Gross margin · 2 charts on 1 dashboard opens the charts that use this field only by way of that measure.
Click a field in the list to open it; Back to … at the top of the inspector returns you to where you were. A chart’s row opens its dashboard, scrolled to that chart and outlined for a moment. While a form has unsaved changes, save or discard them first.
The address bar names the selected part, so a copied link opens the model builder on it, and the browser’s back button returns to it.
Lineage reads your draft. Once the model is published, switch it to the published version, the one dashboards read. Dashboards you can’t see aren’t named: the list says how many more there are and that it isn’t complete.
In the Fields tab, a small number at the end of a field’s row counts the charts and filters that use it.
When you rename a measure or a calculated dimension that charts use, a message says what happens to them. On a published model, they follow the new name when you publish; See where opens the map on that field. On a model that has never been published, the charts keep the old name and show it as missing until they’re changed.
The lineage map
Section titled “The lineage map”To see the whole chain at once, click Open map at the foot of the Lineage section (on a wide enough screen). The map lays everything out from left to right in the direction data flows: tables, then columns, then the measures built on them, then charts and filters, then their dashboards.
- Direction shows what the field comes from, what uses it, or both. Steps sets how far out to go, up to three.
- Click a part to select it. Its whole chain stays dark and everything else fades. The panel on the right says what it is, lists its own lineage, and offers Open in model, Open on its dashboard or Map from here, which draws the map around that part instead.
- A dashboard with many charts shows a few and a +N more card. Click it to show the rest.
- With the keyboard, Tab to a part, use the arrow keys to follow its lines (right to what uses it, left to what it comes from, up and down within a column), and Enter to select it. Escape closes the map.
- The List tab says the same in text: each part with what it comes from and what uses it.
The map reads your draft unless you pick the published version. A very large chain stops at 150 parts and says so; narrow it with Steps or Direction. Dashboards you can’t see are counted, never named. The address bar records the open map, so a copied link opens it too.
Explore
Section titled “Explore”Explore lets you query a model’s fields without SQL, so you can test a measure before anyone builds on it. Open it with Explore in the model builder’s header.
- Click a measure, a dimension, or both. Fields that can’t be combined with your picks are dimmed; hover one to see why.
- Use Filter rows to add conditions, and pick a row limit.
- Read the result: the query as a sentence, then the rows. Show SQL reveals the exact query Riff BI wrote.
- To see the rows as a chart, pick a chart type in the row of icons above the result (bar, line, area, KPI, donut, combo, or the table). A type that can’t draw your fields stays dimmed; hover it to see what’s missing, such as a measure. The choice is kept in the page address, so a copied link opens the same view.
Use Model version to query the draft you’re editing or any published version.
Adding a result to a dashboard
Section titled “Adding a result to a dashboard”When a result is worth keeping, click Add to dashboard in the header. It’s there for anyone who can create or edit dashboards.
- Check the preview. It starts on the chart that suits your fields (a KPI for one number, a line for a date, a bar for a category), and you can change it with the same icons.
- Edit the chart title if you like.
- Choose Existing dashboard (the ones on this model you can edit, the one you touched last first) or New dashboard and give it a name. A new dashboard goes in your Personal folder.
- Click Add chart. A message confirms it, with Open to go to the dashboard. You stay in Explore, so you can keep going.
- The chart lands in the next free spot; drag it into place on the dashboard.
- The dialog says when a field doesn’t fit the chart type and won’t be added. Filters set in Explore aren’t saved on the chart; add them as dashboard filters afterwards.
- Add to dashboard is dimmed, with the reason on hover, while the model has no published version or you’re looking at a draft that differs from the published one. Dashboards read the published model, so pick a published version in Model version.
Publishing
Section titled “Publishing”Edits stay in the draft. Dashboards read the published version, so publish when the model is ready for them.
- Click Publish. One line at the top says what this publish does to the dashboards on the model.
- If anything blocks publishing, it’s listed under Fix these first.
- Add a short message saying what changed, and publish.
Before you publish, the dialog sorts each change by what it does to the charts and filters built on it:
- Broken: the change removes a field a chart or filter uses. Each one is listed with what it will say (“Region is no longer in the model”). To publish anyway, tick the box that names how many will break; the button then reads Publish anyway. If the breakage changes before you publish (someone edits a dashboard), the dialog says so and asks again.
- May change: a formula, filter, source table or join changed, so the numbers may differ. Charts that use the field through another one say so (“Through Gross margin”). Publishing doesn’t need a tick.
- Still works: renames, labels and descriptions. Charts follow a new name on publish.
Open beside a dashboard opens it for editing in a new tab, so you can fix a chart first; the dialog checks again when you come back. Charts that were already broken are listed for information and never hold up publishing. Every change is still listed under All changes. Publish the first version before creating a dashboard. An existing dashboard whose model has never been published shows This model isn’t published yet; it never reads the draft, even in the builder.
- History lists every published version, with its message, and your draft changes. You can restore an earlier version into the draft.
- Renaming a field is carried through to dashboards when you publish.
- Removing a field that a dashboard uses leaves that chart broken; it says which field is missing. The delete confirmation lists the dashboards that use it first, and a measure or calculated dimension that others are built on can’t be deleted until they change (the confirmation opens them for you).
- Deleting a model is for Modelers and Admins, and asks you to confirm.