> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ontology

> Query data using your semantic layer

When enabled, Ana uses your configured ontology (semantic layer) to understand your data relationships, business definitions, and pre-configured joins. Instead of writing raw SQL, Ana can query using business-friendly concepts like "metrics" and "dimensions" that you've pre-defined.

> [!NOTE]
>
> **Consistency Guaranteed:** With Ontology enabled, the same metric always produces the same calculation—ensuring everyone in your organization gets aligned results.

![Ontology tool showing metrics and dimensions](https://mintcdn.com/textql/_MjEsXv_WMgj05pB/images/tool/ontology.png?fit=max\&auto=format\&n=_MjEsXv_WMgj05pB\&q=85\&s=8b67f6c0a0db395255614e663a36f6d2)

Ana using ontology to explore database structure and query metrics

##  You Define the Structure

Users create and customize their own ontology by defining these core components:

> [card] Objects
>
> Your business entities that map to database tables
>
> **Example:** Customers, Orders, Products

> [card] Metrics
>
> Pre-defined calculations with exact SQL logic
>
> **Example:** "Total Revenue", "Customer Lifetime Value"

> [card] Dimensions
>
> Attributes for grouping and filtering data
>
> **Example:** "Order Date", "Customer Region"

> [card] Links
>
> Relationships between different objects
>
> **Example:** "Orders belong to Customers"

> [!TIP]
>
> **Quality Matters:** The more accurately you define your ontology, the more fine-tuned and consistent your results will be. Each metric includes the exact SQL logic needed to calculate it.

##  How It Differs from Text to SQL

> [tab] Quick Comparison
>
> | Feature | Text to SQL | Ontology |
> | - | - | - |
> | **Query Generation** | Generates SQL from scratch each time | Uses pre-defined metric SQL |
> | **Consistency** | May vary between queries | Same metric = same calculation always |
> | **Business Logic** | Ana figures it out on the fly | Pre-configured by you |
> | **Complexity** | Can handle simple queries well | Excels with complex data models |
> | **Setup Required** | None | Requires ontology configuration |

> [tab] Text to SQL
>
> ### How It Works
>
> Generates SQL queries directly from natural language, requiring Ana to figure out table joins, column names, and business logic on the fly. Every query is generated from scratch.
>
> ### Best For
>
> * Ad-hoc exploration
> * Simple queries
> * Quick analysis
> * When you don't have an ontology
>
> ### Limitations
>
> * May interpret metrics differently each time
> * Requires Ana to infer business logic
> * Can be inconsistent across queries

> [tab] Ontology
>
> ### How It Works
>
> Uses your pre-configured semantic layer where you've already defined business objects, metrics (like "Total Revenue"), dimensions (like "Date"), and relationships. Ana queries using these high-level concepts through "Metrics Queries" that execute only the specific SQL logic you've associated with each metric.
>
> ### Best For
>
> * Consistent reporting
> * Complex data models
> * Organization-wide metrics
> * Enforcing business definitions
>
> ### Advantages
>
> * Same metric = same calculation always
> * Pre-configured business logic
> * Handles complex joins automatically
> * Scales with data model complexity

##  When to Use

Enable the Ontology tool when:

**1. You Have an Ontology Configured**

An ontology must be built and configured for your data warehouse before you can use this tool.

**2. You Need Consistency**

When metric calculations must be consistent across your organization and over time.

**3. Complex Data Models**

Your data model has many tables with intricate relationships that are hard to explain each time.

**4. Enforce Business Logic**

You want to ensure everyone uses the same definitions and calculation methods.

**5. Pre-Defined Metrics**

You're asking questions about metrics that have already been defined in your ontology.

> [!WARNING]
>
> **Investment Pays Off:** The more effort you invest in defining your ontology, the more reliable and business-aligned your results will be.

##  Benefits

> [card] Consistency
>
> Everyone gets the same numbers for the same metrics—no more "version of the truth" debates

> [card] Efficiency
>
> No need to explain complex joins and calculations repeatedly—they're pre-configured

> [card] Governance
>
> Control how metrics are calculated and ensure compliance with business rules

> [card] Self-Service
>
> Non-technical users can query using business terms without knowing SQL

> [card] Documentation
>
> Your ontology serves as living documentation of your data model

> [card] Scalability
>
> As your data model grows, the ontology handles increased complexity gracefully

##  Building Your Ontology

Ready to create or enhance your ontology? Check out these resources:

> [card] [Ontology Overview](https://docs.textql.com/core/ontology/overview.md)
>
> Learn the fundamentals of ontologies and how they work in TextQL

> [card] [Creating Objects](https://docs.textql.com/core/ontology/build-your-ontology.md)
>
> Define your business entities and map them to database tables

> [card] [Defining Metrics](https://docs.textql.com/core/ontology/build-your-ontology.md)
>
> Create calculations with business logic that everyone can use

> [card] [Setting Up Links](https://docs.textql.com/core/ontology/build-your-ontology.md)
>
> Configure relationships between your objects

> [card] [Writing Queries](https://docs.textql.com/core/ontology/build-your-ontology.md#ontology-query---tql-files)
>
> Learn how to query your ontology effectively

> [card] [TQL Reference](https://haym.me/tql_manual.html)
>
> Language reference for writing parameterized ontology queries in TQL

> [card] [Why Use Ontology?](https://docs.textql.com/core/ontology/overview.md)
>
> Understand the value proposition and use cases

##  Best Practices

> [accordion] Start with Core Metrics
>
> Begin by defining your organization's most important and frequently-used metrics. Don't try to model everything at once.
>
> **Examples:**
>
> * Revenue metrics (MRR, ARR, Total Revenue)
> * Customer metrics (CAC, LTV, Churn Rate)
> * Operational metrics (Conversion Rate, Average Order Value)

> [accordion] Use Clear Naming
>
> Name your objects, metrics, and dimensions using familiar business terminology that everyone understands.
>
> **Good:** "Monthly Recurring Revenue", "Customer Lifetime Value"
>
> **Avoid:** "mrr\_calc\_v2", "ltv\_formula"

> [accordion] Document Your Logic
>
> Add descriptions to your metrics explaining what they calculate and when to use them. This helps users understand which metric to choose.

> [accordion] Version Control Changes
>
> When updating metric definitions, consider the impact on historical reports. Document changes and communicate them to your team.

> [accordion] Regular Reviews
>
> Periodically review your ontology with business stakeholders to ensure it still reflects current business logic and requirements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.