# How metrics work

> Why Orcabase asks you to define each number once, and how data models, metrics and metric queries fit together to keep answers consistent.

Source: https://tini.so/docs/semantic-layer

Ask three people what “revenue” means and you can get three answers: every order, only paid orders, or paid orders minus refunds. A chart built on the wrong one looks just as convincing as the right one. So does an AI answer. The fix is to write each definition down once, check it, and have everything use it. In Orcabase, that’s the **semantic layer**: **data models** and **metrics**.

1. **Data model**: `orders`. Group by created_at and plan. Add up paid_amount.
2. **Metric**: Revenue ✓. Sum of paid order amounts, refunds excluded. Certified by Finance.
3. **Metric query**: Revenue by month. Last 90 days, split by plan.
4. **Result**: A chart, anywhere. The same number on dashboards, in the agent and in Claude.

A metric is asked for by name. Orcabase writes the SQL for your database each time, from the current definitions.

## The three pieces

- A [data model](https://tini.so/docs/data-models) describes one table in business terms: what you can group and filter by (**dimensions**, like order date, plan or country), what you can add up or count (**measures**, like paid amount or number of orders) and how it joins to other tables.
- A [metric](https://tini.so/docs/metrics) is a named business number built on a model’s measure, with a description, an owner and a format: *Revenue*, *Average order value*, *Net revenue*. Someone checks it and clicks **Certify**, and it becomes the definition everyone uses.
- A [metric query](https://tini.so/docs/metric-queries) asks for metrics by name: Revenue, by month, split by plan, last 90 days. Orcabase writes the SQL for your database from the current definitions.

## Why it’s worth the few minutes

- **One number everywhere.** Dashboards, notebooks, the Data Agent and Claude or ChatGPT all get Revenue from the same definition, so they agree.
- **Fix it once.** Saved metric queries store the metric’s name, not SQL. Change the definition and every chart that uses it is right on its next run.
- **Better AI answers.** The agent checks your certified metrics first, and says which definition it used. Without them, it has to guess what your columns mean from their names.
- **Clear ownership.** Every change is recorded with who made it, and a certified metric shows who vouched for it.

## Correct or loud, never wrong

Some questions can’t be answered safely from a model. The classic case: adding up order amounts while splitting by product, when each order has several products, counts every order once per product and inflates revenue. Orcabase checks each join’s relationship, and refuses a query like that with an explanation instead of returning a plausible wrong number:

> **Note: For example**
>
> *orders can’t be grouped or filtered by order_items: the path orders → order_items crosses a one-to-many join and would double-count. Define the metric on order_items.*

## Get started

The quickest start is to ask the agent: “Model our orders table and draft a revenue metric.” It reads the table, drafts a model and a metric, and tests them. You review and certify. To do it by hand, start from [a table in Explore](https://tini.so/docs/data-models#create).

- [Data models](https://tini.so/docs/data-models): Dimensions, measures and joins.
- [Metrics](https://tini.so/docs/metrics): Define, certify and govern your key numbers.

---

Previous: [Notebooks](https://tini.so/docs/notebooks.md) · Next: [Data models](https://tini.so/docs/data-models.md)

All docs: https://tini.so/llms.txt