Skip to content
M↓ View as Markdown ↗

Overview

The semantic layer is how AI Analysts understand your business data. Instead of querying raw warehouse tables and guessing what your schema means, they work from business definitions that your data team writes and maintains. It translates between how people talk about your business and how the warehouse stores the data.

Availability

  • Who can do this: members with the Edit capability in the active Workspace can view and change the semantic layer in Studio.

What is the semantic layer?

The semantic layer is where you define:

  • What your data represents: Models built on your warehouse tables or SQL queries
  • What attributes matter: Dimensions you can filter and group by
  • What numbers to calculate: Measures on Models, and Metrics for your KPIs
  • How entities connect: Relationships between Models
  • How people talk: Glossary terms that map business vocabulary to your data

When someone asks an AI Analyst "How many active customers do we have?", the semantic layer tells it:

  • What "customers" means (which Model)
  • What "active" means (which filter to apply)
  • How to count them (which measure to use)

One semantic layer per Workspace

Each Workspace has its own semantic layer. Models, Metrics, Glossary terms and Tags belong to the Workspace they were created in, and nothing in one Workspace's semantic layer is visible from another Workspace. Model, Metric and Glossary term names must be unique within a Workspace. See Workspaces.

The three main components

1. Models

Models represent your core business entities: customers, orders, products, transactions, users. Each Model is built from a table or a SQL query on one data connection and defines:

  • Dimensions: attributes you can filter, group or analyze by
  • Measures: numbers you want to aggregate (count, sum, average)
  • Filters: predefined conditions that narrow the data
  • Relationships: how this Model joins to other Models

Example: A customers Model might include dimensions such as customer_tier and created_at, a measure such as total_customers, and a filter such as premium_customers_only.

Go to the Models documentation →

2. Metrics

Metrics are named business calculations built on top of Models. While measures perform aggregations on a single Model, Metrics encode your key performance indicators, such as conversion rates, revenue per customer or weekly active users.

Metrics can:

  • Combine multiple measures
  • Use the filters defined on the Models they are built on: default filters always apply, and you choose which optional filters the AI Analyst may use with the Metric
  • Span multiple Models
  • Control which dimensions make sense for grouping

Example: average_order_value combines order amounts with order counts to calculate typical purchase size.

Go to the Metrics documentation →

3. Glossary

The Glossary maps business terminology to your semantic layer. Your team doesn't talk in database schemas; they use terms like "quotes", "active users" or "recent orders". Glossary terms bridge that gap.

For each Glossary term, you can:

  • Define what it means in your business context
  • Add synonyms for variations
  • Map it to relevant Models, dimensions, filters, measures and Metrics

Example: A "Premium Users" term might map to the customers Model and a filter for premium-tier accounts.

Go to the Glossary documentation →

Tags

You can add Tags to Models and Glossary terms. You can filter the Glossary list by Tag, and Tags control access: an AI Analyst can be set up to use every Model that carries certain Tags, or every Model except those that carry certain Tags. Tags are shared across a Workspace, so the same Tag can label both Models and Glossary terms. See Tags.

How it works

When someone asks an AI Analyst a question:

  1. The AI Analyst identifies business terms in the question ("customers", "last month", "revenue").
  2. It looks up those terms in the Glossary to find the relevant parts of the semantic layer.
  3. It uses Models to understand what data is available and how entities connect.
  4. It applies filters and measures to narrow and aggregate the data.
  5. It uses Metrics when the question involves a defined KPI.
  6. It returns results based on the business rules you defined.

In Studio, the semantic layer has three sections in the sidebar:

  • Models: define your business entities and their components
  • Metrics: create business calculations
  • Glossary: map business vocabulary to your data

Each list shows every item's name and a short description (the definition, for Glossary terms). Use the search box at the top of the list to find an item, and the filter button next to it to narrow the list:

List Filters
Models Data source; Empty field: Empty description, Empty guidance or Empty tags
Metrics Model; Empty field: Empty description or Empty guidance
Glossary Source (Manual or Catalog), Tag; Empty field: Empty definition or Empty tags

In the Glossary list, terms copied from a connected catalog also show a Synced or Orphaned badge.

To search across the whole semantic layer at once, see Search. To see how Models, Metrics and Glossary terms connect, see Knowledge graph.

Version history

Models, Metrics and Glossary terms keep a version history. Open an item and click Version history to see earlier versions, click View changes to compare them, and click Restore to bring an earlier version back. Restoring records a new version that matches the one you selected; your current version stays in the history. See Version history.

Getting started workflow

Build the semantic layer in this order.

1. Start with Models

  • Create Models for your most important tables (users, orders, products, and so on). See Creating Models.
  • Add dimensions for the key attributes
  • Define measures for basic counts and sums
  • Set up relationships between Models

2. Build Metrics

  • Create Metrics for your key business KPIs
  • Combine measures with business logic
  • Specify which dimensions make sense for each Metric
  • Choose which optional Model filters are available for each Metric

3. Define Glossary terms

  • Add Glossary terms for concepts your team frequently discusses
  • Include synonyms for variations
  • Map terms to relevant Models, dimensions, filters, measures and Metrics

4. Iterate and refine

As your team uses AI Analysts:

  • Add new Models as you connect more data sources
  • Create Metrics when you identify new KPIs
  • Expand your Glossary when you notice AI Analysts misinterpreting terms
  • Update guidance to improve AI Analyst accuracy

SemQL: the query language

AI Analysts use SemQL (Semantic Query Language) to query your semantic layer. You'll also see SemQL in filter expressions and Metric calculations.

SemQL is SQL-shaped and references Models, dimensions and measures by name. It has no {{ }} templating. For example:

  • A filter on the orders Model is written status = 'active'.
  • A Metric expression is written SUM(revenue).
  • A query is written SELECT region, total_revenue FROM orders, where region is a dimension and total_revenue is a measure on the orders Model.

AI Analysts query your data through SemQL, using the Models, Metrics and Glossary terms you define. See Semantic SQL (SemQL).

Keeping it up to date

Steward, the AI assistant in Studio, can keep the semantic layer current by proposing updates to Models, Metrics and Glossary terms for you to review. See Using Steward and Steward Inbox.