Skip to main content

Semantic Layer

The semantic layer is where you define the "truth" of your data — metrics, dimensions, and relationships that the AI agent uses to answer questions accurately.

Why Semantic Layers?​

Without semantic definitions, the AI has to guess how to calculate metrics. With a semantic layer:

  • Consistent metrics — "Revenue" means the same thing everywhere
  • Accurate joins — The AI knows how tables connect
  • Business context — Terms like "active user" have clear definitions
  • Reduced hallucinations — Grounded answers, not guesses

Creating a Semantic Layer​

  1. Go to Semantic Catalog in the sidebar
  2. Click New Semantic Layer
  3. Select a database connection
  4. Enter a namespace (e.g., finance, marketing)
  5. Start defining your model

Core Concepts​

Metrics​

Quantitative measures you want to track:

metrics:
  revenue:
    type: sum
    sql: order_total
    description: Total revenue from orders

  active_users:
    type: count_distinct
    sql: user_id
    filters:
      - last_active_at > current_date - interval '30 days'

Dimensions​

Ways to slice and dice your metrics:

dimensions:
  region:
    sql: shipping_region
    type: string

  order_date:
    sql: created_at
    type: date

Relationships​

How tables connect to each other:

joins:
  - from: orders
    to: customers
    on: orders.customer_id = customers.id
    type: many_to_one

Versioning​

Semantic layers are versioned:

  • Draft — Work in progress, not visible to notebooks
  • Published — Available for notebooks to pin

When you update a semantic layer, create a new version. Existing notebooks continue using their pinned version until you update them.

Pinning to Notebooks​

In a notebook, use the Semantic Pins menu to:

  1. Select which semantic layers to use
  2. Choose specific versions
  3. The AI agent will use these definitions

Best Practices​

Start Small​

Begin with your most important metrics and expand over time.

Use Clear Names​

monthly_recurring_revenue is better than mrr for AI understanding.

Add Descriptions​

Help the AI (and your team) understand what each metric means.

Version Thoughtfully​

Breaking changes should be new versions, not edits to existing ones.

Semantic Catalog​

The catalog shows all semantic layers in your organization:

  • Filter by connection
  • Search by name or namespace
  • See which notebooks use each layer
  • View version history