Semantic Layer

The semantic layer sits on top of database connections and gives agents business context about your data. Instead of raw table/column names, agents understand business terms, relationships, and KPIs.

Why Use a Semantic Layer?

Without a semantic layer, an agent sees:

tbl_ord with columns cust_id, amt, dt

With a semantic layer, the agent understands:

Orders table (purpose: "tracks all customer purchases")
cust_id joins to Customers table
Revenue = SUM(amt) where status = 'completed'
Active Customer = customer with an order in the last 90 days

Initialize the Semantic Layer

Populate the semantic layer from your database schema:

Python

import httpx

HUB_URL = "https://central-hub.example.com/api/v1"
HEADERS = {"X-API-Key": "sk-your-api-key"}

semantic = httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/semantic-layer/initialize",
    headers=HEADERS,
).json()

print(f"Found {len(semantic['config']['tables'])} tables")
print(f"Detected {len(semantic['config']['relationships'])} relationships")

Configure Tables

Update display names, purposes, and domains for tables. You can also exclude tables that agents shouldn't access:

Python

httpx.patch(
    f"{HUB_URL}/data-sources/connections/{connection_id}/semantic-layer/tables/tbl_ord",
    headers=HEADERS,
    json={
        "display_name": "Orders",
        "purpose": "Tracks all customer purchase transactions",
        "domain": "Sales",
        "is_included": True,
    },
)

Add Business Definitions

Define business terms so agents interpret your data correctly:

httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/semantic-layer/definitions",
    headers=HEADERS,
    json={
        "name": "Active Customer",
        "description": "A customer who has placed at least one order in the last 90 days",
        "domain": "Sales",
        "conditions": [
            {
                "field": "orders.created_at",
                "operator": "greater_than",
                "value": "NOW() - INTERVAL '90 days'",
            }
        ],
    },
)

Add KPIs

Define key performance indicators. The system can AI-generate the SQL formula if you only provide a name and description:

Python

# Let the AI generate the formula
kpi = httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/semantic-layer/kpis",
    headers=HEADERS,
    json={
        "name": "Monthly Recurring Revenue",
        "description": "Total recurring revenue from active subscriptions in the current month",
        "tables": ["subscriptions", "payments"],
    },
).json()

print(f"Generated formula: {kpi['formula']}")
print(f"Generated SQL: {kpi['sql']}")

Semantic Layer

Why Use a Semantic Layer?

Initialize the Semantic Layer

Configure Tables

Add Business Definitions

Add KPIs

On this page