> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wayak.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a semantic layer

> Define your business logic so the agent always gets the right answer

A semantic layer teaches the agent how your business thinks about data. Without one, the agent guesses. With one, it answers like your best analyst. This guide walks you through building your first semantic layer.

## What you'll do

1. Define a business metric
2. Map business terminology to your schema
3. Set up table relationships
4. Test the semantic layer in a conversation

## Step 1: Define a metric

Metrics are the calculations your team cares about — revenue, churn rate, conversion, active users. Start with one.

1. Go to **Semantic Layer** in the Wayak dashboard
2. Click **Add metric**
3. Give it a name your team actually uses (e.g. "Revenue")
4. Define the calculation:
   * **Source table** — the table that contains the raw data
   * **Aggregation** — how to compute it (SUM, COUNT, AVG, etc.)
   * **Column** — the column to aggregate
   * **Filters** — any conditions that scope the metric (e.g. `txn_type = 'sale'`)

<Note>Name your metrics the way your team talks. If everyone says "MRR" not "monthly recurring revenue," name it "MRR." The agent matches user questions to metric names.</Note>

## Step 2: Map your terminology

Your team uses business language. Your database uses column names. The semantic layer bridges the two.

1. Go to **Terminology** in the semantic layer settings
2. Add mappings between business terms and schema objects:

| Business term  | Maps to                                    |
| -------------- | ------------------------------------------ |
| "Customers"    | `accounts` table where `status = 'active'` |
| "Sales rep"    | `users` table where `role = 'sales'`       |
| "Last quarter" | Dynamic date filter: previous 3 months     |

When someone asks "How many customers do we have?", the agent knows exactly which table and filter to use.

## Step 3: Define table relationships

Tell the agent how your tables connect so it can join them correctly.

1. Go to **Relationships** in the semantic layer settings
2. Add joins between your tables:
   * **From table** and **To table**
   * **Join key** — the columns that link them
   * **Join type** — inner, left, etc.

This prevents the agent from guessing joins or producing incorrect results when questions span multiple tables.

## Step 4: Test it

Open the Wayak chat and ask a question that uses your new metric or terminology.

* "What's our revenue this month?" — should use your defined Revenue metric
* "How many customers signed up last quarter?" — should use your Customers terminology mapping
* "Revenue by sales rep" — should join tables using your defined relationships

If the answer matches what you expect, your semantic layer is working. If not, refine the definitions and test again.

## What's next

Your agent now understands your business logic. Next, turn your most important questions into a dashboard.

<Card title="Build your first dashboard" icon="grid-2" href="/quickstart/build-a-dashboard">
  Create views, arrange them into a dashboard, and share it with your team.
</Card>