KPI & semantic layer

Why a semantic layer

Raw SQL is error-prone, inconsistent, and doesn’t scale. Different teams define “revenue” differently. Agents can’t understand business context from table schemas alone. The result: every generated dashboard drifts, every report tells a subtly different story, and nobody trusts the data.

Canyon solves this by putting a governed semantic layer between every app, every agent, and the underlying warehouses. Metrics have one definition. Permissions have one enforcement point. Audit trails have one source of truth.

How it works

Agents and apps request a measure (total_revenue) by name. The semantic layer resolves the measure to an optimized query, applies row- and column-level permissions based on the user’s identity, and returns typed results. Pre-aggregations, query caching and audit logging happen transparently.

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│  CANYON SEMANTIC DATA LAYER                                                              │
│  ═══════════════════════════════════════════════════════════════════════════════════════│
│                                                                                          │
│   Natural language query                                                                 │
│   "Show me revenue by region for Q4"                                                     │
│                         │                                                                │
│                         ▼                                                                │
│              ┌─────────────────────┐                                                     │
│              │   CANYON SEMANTIC   │                                                     │
│              │       LAYER         │                                                     │
│              └──────────┬──────────┘                                                     │
│                         │                                                                │
│    ┌────────────────────┼────────────────────┐                                           │
│    ▼                    ▼                    ▼                                           │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐                                    │
│  │ MEASURES │    │  DIMENSIONS  │    │    JOINS     │                                    │
│  │──────────│    │──────────────│    │──────────────│                                    │
│  │ revenue  │    │ region       │    │ orders →     │                                    │
│  │ count    │    │ created_date │    │   customers  │                                    │
│  │ avg_value│    │ status       │    │              │                                    │
│  └──────────┘    └──────────────┘    └──────────────┘                                    │
│                         │                                                                │
│                         ▼                                                                │
│              ┌─────────────────────┐                                                     │
│              │   GOVERNED QUERY    │                                                     │
│              │  + ABAC row filters │                                                     │
│              │  + cache + audit    │                                                     │
│              └─────────────────────┘                                                     │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Connected data sources

The semantic layer talks to your existing warehouses and databases directly. No data is copied into Canyon; queries run where the data already lives.

Metric definitions

Metrics, measures, dimensions and joins are first-class governed entities. They are editable in the Canyon UI, versioned, and re-used across every app and agent in the organization.

Metric definition (YAML)

metrics:
  - name: orders
    source: public.orders

    measures:
      - name: total_revenue
        expression: "SUM(amount)"
        type: sum
        format: currency

      - name: order_count
        expression: "COUNT(*)"
        type: count

    dimensions:
      - name: status
        type: string

      - name: created_at
        type: time

    joins:
      - with: customers
        relationship: many_to_one
        on: "customer_id = customers.id"

Query flow

A user or agent asks a natural-language question. The Conversation Agent discovers available metrics, builds a structured query_metrics call, and the semantic layer does the heavy lifting.

1. get_metric_catalog() — discover available metrics, measures and dimensions for this user.
2. The agent maps intent to a metric and the measures and dimensions it needs.
3. query_metrics(...) — fully-typed, validated, governed request.

query_metrics({
  metric: "orders",
  measures: ["total_revenue"],
  dimensions: ["customer_name"],
  order: [["total_revenue", "desc"]],
  limit: 10
})

What the semantic layer does next

1. Validates the request against the metric schema.
2. Applies RBAC + ABAC filters based on the caller’s identity.
3. Generates an optimized query against the configured warehouse.
4. Runs against cache or warehouse, returns typed results, logs the access.