The Contextual Semantic Layer: Powering Trusted GenAI Analytics

Semantic layers have long provided the metric definitions that enable consistent analytics. But for generative AI applications, traditional semantic layers are not enough. AI needs richer context - not just what metrics mean, but how to use them appropriately.

The contextual semantic layer extends traditional capabilities to provide the full business knowledge AI requires for accurate, trustworthy responses.

Beyond Traditional Semantic Layers

What Traditional Layers Provide

Traditional semantic layers deliver:

• Metric calculations (how to compute revenue)
• Dimension definitions (what customer segment means)
• Join paths (how tables relate)
• Basic documentation (metric descriptions)

This serves BI tools well - they need to generate correct SQL and display labels.

What AI Additionally Needs

AI analytics requires more:

Interpretation guidance: When to use which metric Relationship context: How metrics relate to each other Terminology mapping: What users mean by different terms Business rules: Edge cases and exceptions Appropriate usage: What questions can be reliably answered

Without this context, AI must guess - leading to plausible but often wrong responses.

The Contextual Difference

Traditional semantic layer:

metric: monthly_recurring_revenue
calculation: SUM(subscription.monthly_value) WHERE status = 'active'
description: Total monthly recurring revenue

Contextual semantic layer:

metric: monthly_recurring_revenue
calculation: SUM(subscription.monthly_value) WHERE status = 'active'
description: Total monthly recurring revenue

context:
  business_meaning: |
    MRR represents our predictable monthly revenue from subscriptions.
    It's the primary metric for tracking business growth and is used
    for investor reporting, planning, and performance evaluation.

  common_questions:
    - "What's our MRR?" → Current month MRR
    - "MRR growth" → Month-over-month percentage change
    - "MRR trend" → 6-month history with visualization

  related_metrics:
    - arr: "ARR = MRR × 12, used for annual planning"
    - nrr: "NRR shows expansion/contraction from existing customers"
    - new_mrr: "MRR from new customers acquired this period"

  interpretation:
    - "MRR increases from new customers and expansion"
    - "MRR decreases from churn and contraction"
    - "Compare to plan/forecast, not just prior periods"

  caveats:
    - "Excludes one-time revenue and professional services"
    - "Currency conversion uses end-of-period rates"
    - "Trial subscriptions not included until conversion"

  synonyms:
    - "monthly revenue"
    - "subscription revenue"
    - "recurring revenue"

The contextual version enables AI to understand not just how to calculate MRR but how to use it appropriately.

Components of Contextual Semantic Layers

1. Rich Metric Context

Beyond calculation, each metric includes:

Business meaning: Why this metric matters Common usage patterns: How people typically ask about it Related metrics: What pairs well together Interpretation guidance: How to understand the values Caveats and limitations: What to watch out for

2. Terminology Intelligence

Mapping between user language and technical definitions:

Synonyms: Different words for the same concept

revenue:
  canonical: monthly_recurring_revenue
  synonyms: [MRR, subscription revenue, monthly revenue, recurring]

Disambiguation: When terms could mean multiple things

customers:
  default: active_customers
  variants:
    - "total customers" → all_customers
    - "paying customers" → active_customers
    - "lost customers" → churned_customers

Common phrases: Natural language patterns

patterns:
  - "how are we doing" → performance_summary
  - "compared to last" → period_over_period_comparison
  - "broken down by" → dimension_grouping

3. Relationship Knowledge

How concepts connect:

Metric relationships:

• MRR is a component of ARR
• Churn rate affects NRR
• CAC and LTV should be analyzed together

Entity relationships:

• Customers have subscriptions
• Subscriptions generate revenue
• Revenue rolls up to business units

Analytical relationships:

• Growth analysis requires period comparison
• Cohort analysis needs customer signup date
• Attribution requires touchpoint data

4. Usage Guidance

Appropriate application of metrics:

What questions this metric answers:

• "What's our recurring revenue?"
• "How is subscription growth trending?"

What questions this metric does not answer:

• "What's our total revenue?" (need to add one-time)
• "How profitable are we?" (need cost data)

How to combine with other data:

• "For profitability, pair with cost metrics"
• "For efficiency, compare to customer count"

5. Business Rules

Logic that affects interpretation:

Calculation rules:

• Multi-year contracts are amortized monthly
• Currency conversion uses specific rates
• Trials convert at specific criteria

Exception handling:

• Strategic accounts may have non-standard terms
• Certain products excluded from core metrics
• Time periods may need adjustment for fiscal calendar

Building Contextual Semantic Layers

Start with Core Metrics

Begin where context has the highest impact:

1. Identify your 10-20 most important metrics
2. Document full context for each
3. Validate with subject matter experts
4. Test with actual AI interactions

Capture Tacit Knowledge

Much context exists only in people's heads:

Interview experts: How do analysts think about metrics? Review questions: What do people actually ask? Analyze errors: Where does AI currently fail? Document exceptions: What do experts know that is not written?

Structure for AI Consumption

Organize context for effective AI use:

Consistent format: Same structure for all metrics Machine-readable: YAML, JSON, or similar Version controlled: Track changes over time Connected: Links between related concepts

Iterate Based on Usage

Context improves through use:

Monitor accuracy: Where does AI get it wrong? Capture feedback: What do users correct? Identify gaps: What questions cannot be answered? Expand coverage: Add context where needed

Contextual Layers in Practice

Query Understanding

Context helps AI interpret questions correctly:

User: "How's growth looking?"

Without context: AI might calculate any growth metric, any time period With context: AI knows "growth" typically means MRR growth, month-over-month, and compares to plan

Answer Generation

Context improves response quality:

Without context: "MRR was $10.2M" With context: "MRR was $10.2M, up 3.5% from last month and 2% ahead of plan. Enterprise segment drove most growth at 8%."

Appropriate Boundaries

Context enables appropriate refusals:

Without context: AI attempts to answer any question With context: AI recognizes when questions are outside reliable scope and responds appropriately

The Codd AI Approach

Codd AI is built around contextual semantic layers:

Rich context capture: Tools for documenting full metric context Terminology management: Mapping user language to definitions Relationship modeling: Connections between concepts Usage guidance: What can and cannot be reliably answered

This contextual foundation is why Codd AI can provide accurate, trustworthy answers - the AI has the business knowledge needed to respond like an expert analyst.

Contextual Layer Maturity

Level 1: Basic Definitions

• Metric calculations documented
• Basic descriptions available
• Minimal additional context

AI can generate queries but may misinterpret questions.

Level 2: Terminology Mapping

• Synonyms documented
• Common phrases mapped
• Disambiguation rules defined

AI interprets questions more accurately.

Level 3: Rich Context

• Business meaning documented
• Relationships captured
• Interpretation guidance included
• Caveats and limitations noted

AI provides nuanced, appropriate responses.

Level 4: Adaptive Context

• Context learns from usage
• Gaps automatically identified
• Continuous improvement built in

AI accuracy improves over time automatically.

Investment and Returns

Investment Required

Building contextual semantic layers requires:

• Expert time to document context
• Process to capture tacit knowledge
• Infrastructure to store and serve context
• Ongoing maintenance as business evolves

Returns Achieved

Contextual semantic layers deliver:

• Significantly higher AI accuracy
• Reduced need for AI supervision
• Broader user adoption
• Greater trust in AI responses
• Foundation for expanding AI use cases

The investment in context pays dividends across all AI-powered analytics initiatives.

For organizations serious about AI analytics, the contextual semantic layer is not optional - it is the foundation that makes everything else work.