# The semantic fluid

> One vocabulary for your business, written down once and shared by queries, cherry, reports and AI assistants, so everyone gets the same number.

A warehouse holds rows. It does not know that `total` on an invoice is before discounts, that a "paid invoice" is one where `status` is `'PAID'`, or that the `customer_id` on an invoice is the same customer as the `customer_id` on a support ticket. The semantic fluid holds that knowledge. It is the list of tables that matter, the numbers you report, the ways you slice them, and how the tables join, all in your business's own words.

You find it in the console under **Intelligence · Semantic fluid**.

## Why it exists

Two people asking "what was revenue last month?" get two different numbers unless someone has decided what revenue means. An AI assistant left alone with a table guesses that `amount` is revenue and returns a number nobody can audit.

The fluid takes the guess out. You define `net revenue` once. A query, a report, cherry and an AI assistant all use that definition, so they all return the same figure. When the definition changes, every one of them changes with it.

Nothing sanda proposes goes live unreviewed. Suggestions from your data wait in a queue, and only definitions you accept reach an answer. See [review what sanda proposes](https://docs.sanda-os.com.au/semantic-fluid/review).

## What it contains

| Kind | What it holds | Example |
|---|---|---|
| Tables | The tables sanda may read, whether each is a fact or a dimension, its grain, key and event time | `invoices`: one row per invoice, keyed on `invoice_id`, timed by `issued_at` |
| Metrics | A number defined once, as SQL over one table | `net revenue` is `{gross revenue} - sum(discount_amount)` for paid invoices |
| Dimensions | A column you slice by, and how a date rolls up | `issued date` rolls up from day to month to quarter to year |
| Filters | Named conditions that say which rows count | `paid invoices` is `status = 'PAID'` |
| Relationships | Which tables join, on which columns, and which end holds one row | one `customers` row to many `invoices` |
| Aliases | The other words your team uses for a table or a column | `invoices` is also called `sales ledger` |
| Value labels | Report labels for stored codes | `AUTHORISED` is shown as `approved` |
| Categories | One word for a way of slicing, across every column that carries it | `region`, over two source systems |
| Datasets | Groups of tables, each with a colour on the map | `billing`, `support` |
| Glue | Column pairs that join two datasets | a contact's email in one system, a customer's email in another |

Each kind has its own page. Start with [tables and datasets](https://docs.sanda-os.com.au/semantic-fluid/tables), [metrics](https://docs.sanda-os.com.au/semantic-fluid/metrics) and [relationships](https://docs.sanda-os.com.au/semantic-fluid/relationships).

## Who uses it

The same definitions answer every one of these:

- **The workbench.** [Query the fluid](https://docs.sanda-os.com.au/semantic-fluid/query-the-fluid) lets you pick a metric, a dimension and a filter and see the rows, with no AI involved.
- **cherry.** [Ask cherry](https://docs.sanda-os.com.au/cherry/ask) a question and it looks up your metrics and tables by name, then runs them.
- **Reports.** Blocks on a report are built from the same metrics, dimensions and filters. See [reports](https://docs.sanda-os.com.au/reports).
- **AI assistants.** Claude, ChatGPT and other assistants connect over [MCP](https://docs.sanda-os.com.au/mcp) and read the same vocabulary.
- **Excel and Power BI.** The [OData feed](https://docs.sanda-os.com.au/odata) is built over the fluid.
- **sanda search.** A [search service](https://docs.sanda-os.com.au/search) can only index a table that is on the map, and only the columns you put there.

## What "on the map" means

The fluid is also a boundary. sanda answers questions only from tables you have put on the map, and only from the columns you ticked when you added each one. A table that is not on the map does not exist to cherry, to a report or to an AI assistant, and a column you left out cannot be read.

This is why adding a table is a deliberate step. See [what the agent is told](https://docs.sanda-os.com.au/semantic-fluid/agent-context) for exactly what an agent can see.

## How it relates to the warehouse

The warehouse holds your data. The fluid holds what the data means. The fluid stores definitions, never a copy of your numbers: a number is worked out from the warehouse each time someone asks.

```text
connections and uploads
    ↓ land rows in
your warehouse (landing tables)
    ↓ you put a table on the map
mapping views: only the tables and columns you chose
    ↓ read through
the semantic fluid: tables, metrics, dimensions, filters, relationships, names
    ↓ answers
the workbench, cherry, reports, AI assistants, Excel and Power BI
```

When you add a table, sanda publishes it as a view named `mapping.<table>` over exactly the columns you ticked. That view is what questions read. Your landing tables stay untouched. See the [warehouse](https://docs.sanda-os.com.au/warehouse) for how data gets there.

While a workspace has no warehouse of its own, the map shows sanda's [learning dataset](https://docs.sanda-os.com.au/reference/glossary#learning-dataset), a sample business you can explore. As soon as you have a healthy warehouse of your own, its map replaces the sample.

## How it stays current

- **Review keeps it honest.** Run [Learn from my data](https://docs.sanda-os.com.au/semantic-fluid/learn) again after new data lands. Proposals extend what you have and never overwrite a definition you accepted.
- **A synced table's view follows its source.** When a source stops sending a column, sanda rebuilds the table's `mapping` view over what is left, and the card's column list follows. A column a sync adds is not offered to agents until you tick it under **columns…** on the table's card. See [tables and datasets](https://docs.sanda-os.com.au/semantic-fluid/tables#choose-the-columns).
- **A definition is a rule, not a stored number.** Change a metric and the next question, report run or agent answer uses the new definition.

:::note
While a table is being refreshed by a sync, a question over it can briefly answer that the table has no rows attached and its sync is finalising. Ask again in a few minutes, and check the connection's status if it keeps happening.
:::

## Where to go next

:::links
- [The map](https://docs.sanda-os.com.au/semantic-fluid/the-map): Cards, lines and the panels around them.
- [Learn from my data](https://docs.sanda-os.com.au/semantic-fluid/learn): Have cherry read your warehouse and propose a first model.
- [Naming rules](https://docs.sanda-os.com.au/semantic-fluid/naming): Why every name is lowercase, and what a name does.
- [What the agent is told](https://docs.sanda-os.com.au/semantic-fluid/agent-context): Read exactly what an AI receives.
:::