What is a Semantic Layer? Definition and Examples

A semantic layer is a business logic abstraction between your data warehouse and the tools that query it. It defines metrics, dimensions, and access rules once so every dashboard, API, and AI agent returns consistent numbers. Without one, "revenue" gets defined differently in every Looker view, dbt model, and ad-hoc SQL query. A semantic layer makes the metric definition authoritative: one source of truth, consumed by every downstream tool. For B2B SaaS teams running customer-facing analytics, it also handles multi-tenancy and row-level security at the query layer.

How does a semantic layer work?

A semantic layer organizes your data warehouse into cubes, measures, and dimensions defined in YAML. Each cube maps to a business entity (orders, customers, subscriptions) and declares the SQL source, aggregations, and relationships.

cubes:
  - name: orders
    sql_table: public.orders

    measures:
      - name: total_revenue
        sql: amount
        type: sum
      - name: order_count
        type: count

    dimensions:
      - name: status
        sql: status
        type: string
      - name: created_at
        sql: created_at
        type: time

Views expose curated subsets of cubes for specific use cases. Your marketing team gets one set of metrics. Your AI agent gets another. Same underlying definitions, different interfaces. When an agent or dashboard queries a measure, the semantic layer generates the correct SQL, applies access control, and returns the result. Relationships between cubes (like orders belonging to customers) are declared once and reused across queries, so JOINs are always correct. This eliminates the most common source of wrong numbers in analytics: inconsistent JOIN logic written independently by different teams or AI models.

What problems does a semantic layer solve?

Metric inconsistency. Without a central definition, "revenue" means different things in different dashboards. One team includes refunds, another excludes them, and the board deck matches neither. A semantic layer defines each metric once. Every consumer gets the same number.

Ungoverned AI access. AI agents writing SQL against raw tables guess at JOINs and invent aggregations. A semantic layer constrains what agents can query through typed tools like explore_schema and query via MCP. No hallucinated metrics.

No multi-tenancy. B2B products need each customer to see only their data. A semantic layer applies row-level security per tenant automatically, scoped by publishable keys. No per-customer databases.

How Bonnard implements the semantic layer

The semantic layer is defined in YAML and deployed with bon deploy. Cubes, measures, dimensions, and views live in version control alongside your application code. The pre-aggregation cache stores frequent queries for millisecond responses. Definitions go through pull requests with reviewable diffs, so metric changes are tracked with the same rigor as application code changes.

Every surface queries the same definitions: MCP for AI agents, React SDK for embedded analytics, TypeScript SDK for internal tools, and REST API for everything else. Change a metric definition, run bon deploy, and every surface reflects the update. There is no sync step between surfaces. The semantic layer is the single query engine, so consistency is structural, not procedural.

Read the full guide at /semantic-layer.

Related terms

• Pre-Aggregation
• Metric Governance
• MCP