Semantic Insights

Query structured data models using business-friendly metrics and dimensions without writing SQL.

Best for:

• Business metric reporting
• KPI dashboards
• Cross-functional analytics
• Model-based queries

Example use cases:

• "What's our monthly recurring revenue by region?"
• "Show customer acquisition cost by marketing channel"
• "Track product adoption metrics over time"

Understanding the Semantic Layer

The semantic layer provides a business-friendly abstraction over your raw data:

• Metrics: Pre-defined calculations (revenue, conversion rate, DAU)
• Dimensions: Attributes to slice data by (region, plan type, channel)
• Time dimensions: Date/time groupings (day, week, month, quarter)
• Relationships: How tables connect (users → orders → products)

Creating Semantic Insights

Reference semantic models to build queries without SQL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Example: Query semantic model via API
{
  "semantic_definition": {
    "model": "sales",
    "metrics": ["revenue", "order_count", "avg_order_value"],
    "dimensions": ["product_category", "customer_segment"],
    "time_dimension": "order_date",
    "granularity": "month"
  },
  "filters": {
    "order_date": { "gte": "2025-01-01" },
    "customer_segment": ["enterprise", "mid-market"]
  }
}

Semantic Model Structure

Semantic models define reusable business logic:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Example semantic model definition
table: sales
schema: analytics
description: Sales and revenue metrics
measures:
  - as: revenue
    type: sum
    sql: amount
  
  - as: order_count
    type: count_distinct
    sql: order_id
  
  - as: avg_order_value
    type: average
    sql: amount
dimensions:
  - as: product_category
    type: string
    column: category
  
  - as: customer_segment
    type: string
    column: segment
  
  - as: order_date
    type: datetime
    column: created_at

Benefits of Semantic Layer

• Consistency: Everyone uses the same metric definitions
• Accessibility: No SQL knowledge required
• Governance: Centralized business logic
• Reusability: Define once, use everywhere
• Type safety: Validated metrics and dimensions

Querying Semantic Models

Behind the scenes, semantic queries automatically generate optimized SQL based on your metric and dimension selections. The semantic layer handles joins, aggregations, and time groupings, so you can focus on selecting the metrics and dimensions you need without writing SQL. The generated queries are optimized for performance and leverage indexes and caching automatically.

For more complex queries that require custom logic, consider using SQL insights instead.