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

# Semantic Layer

> Define governed metrics and dimensions in YAML for consistent answers.

The semantic layer lets you define metrics, dimensions, and joins once so dazense answers consistently and transparently.

<Note>
  The semantic layer governs metric meaning. It does not replace policy enforcement. For hard controls (PII, scope, contracts), use Trusted Analytics V1.
</Note>

## Create a semantic model

Create `semantics/semantic_model.yml`:

```yaml theme={null}
models:
  customers:
    table: customers
    schema: main
    description: Customer master data
    primary_key: customer_id
    dimensions:
      customer_id:
        column: customer_id
      first_name:
        column: first_name
      last_name:
        column: last_name
    measures:
      customer_count:
        type: count

  orders:
    table: orders
    schema: main
    description: All orders placed by customers
    primary_key: order_id
    time_dimension: order_date
    dimensions:
      status:
        column: status
    measures:
      order_count:
        type: count
      total_revenue:
        column: amount
        type: sum
      avg_order_value:
        column: amount
        type: avg
    joins:
      customer:
        to_model: customers
        foreign_key: customer_id
        related_key: customer_id
        type: many_to_one
```

## Measure types

* `count`, `sum`, `avg`, `min`, `max`, `count_distinct`

## Add deterministic filters to critical measures

For business-critical metrics (for example revenue), encode exclusions directly in the measure definition:

```yaml theme={null}
total_revenue:
  column: amount
  type: sum
  filters:
    - column: status
      operator: not_in
      value: [returned, return_pending]
```

This prevents LLM-dependent interpretation drift.

## Join types

* `many_to_one`, `one_to_one`, `one_to_many`

When a semantic model is present, the agent uses `query_metrics` for covered questions to avoid ad‑hoc SQL and keep logic governed.

## Mode behavior

* **Direct Analytics**: semantic model optional
* **Trusted Analytics V1**: semantic model strongly recommended (often required for critical metrics)
* **Trusted Analytics V2**: same as V1, with metadata enrichment from OpenMetadata