> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/stage-2-productize/define-models-and-logic/semantic-models.md).

# Semantic models

The semantic model is the interface between your physical warehouse tables and the people or systems that query them. It maps raw column names to meaningful business concepts: measures that can be aggregated, dimensions that can be grouped by, and segments that can be filtered on.

Without a semantic model, consumers must write SQL and know exactly which table to query. With one, they can ask queries against governed, consistent definitions that resolve the same way every time.

***

## Two-layer semantic structure

Vulcan's semantic layer consists of two types of files:

| File type                                                                                                 | Kind             | What it defines                                                                                          |
| --------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------- |
| [Semantic models](/build/stage-2-productize/define-models-and-logic/semantic-models/semantic-models.md)   | `kind: semantic` | Dimensions, measures, segments, and joins. Wraps a single physical model.                                |
| [Business metrics](/build/stage-2-productize/define-models-and-logic/semantic-models/business-metrics.md) | `kind: metric`   | Time-series analytical definitions. Combines a measure, a time column, and optional grouping dimensions. |

***

## What orders-analytics defines

`orders-analytics` has six semantic models and five business metrics:

**Semantic models** (`models/semantics/`):

| File                            | Wraps                            | What it exposes                                                                          |
| ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
| `daily_sales.yml`               | `silver.fct_daily_sales`         | Revenue, order volume, item count, shipment rate by date, region, customer, and product. |
| `weekly_sales.yml`              | `silver.fct_weekly_sales`        | Weekly revenue rollups by region and category.                                           |
| `customer_profile.yml`          | `silver.dim_customer_profile`    | Customer lifetime metrics, segments, and recency. Joined to `daily_sales`.               |
| `product_profile.yml`           | `silver.dim_product_profile`     | Product sales velocity and performance tier. Joined to `daily_sales`.                    |
| `rfm_customer_segmentation.yml` | `gold.rfm_customer_segmentation` | RFM scores and segment labels. Joined to `customer_profile`.                             |
| `sales_funnel_analysis.yml`     | `gold.sales_funnel_analysis`     | Regional funnel: registration to order to shipment conversion.                           |

**Business metrics** (`models/metrics/`):

| File                          | What it measures                                      |
| ----------------------------- | ----------------------------------------------------- |
| `daily_sales_performance.yml` | Daily revenue by region and category                  |
| `weekly_revenue_trends.yml`   | Weekly revenue trends                                 |
| `customer_lifetime_value.yml` | Average customer lifetime value by segment and region |
| `rfm_value_by_segment.yml`    | RFM monetary value by segment                         |
| `fulfillment_conversion.yml`  | Order-to-shipment conversion rate by region           |

***

## File locations

```
models/
├── semantics/
│   ├── daily_sales.yml
│   ├── weekly_sales.yml
│   ├── customer_profile.yml
│   ├── product_profile.yml
│   ├── rfm_customer_segmentation.yml
│   └── sales_funnel_analysis.yml
└── metrics/
    ├── daily_sales_performance.yml
    ├── weekly_revenue_trends.yml
    ├── customer_lifetime_value.yml
    ├── rfm_value_by_segment.yml
    └── fulfillment_conversion.yml
```

***

## How the layers connect

```
Physical model (silver.fct_daily_sales)
        |
        v
Semantic model (kind: semantic, name: daily_sales)
  Dimensions: order_date, region_name, customer_id, category
  Measures:   total_daily_revenue, total_daily_orders, average_shipment_rate
  Segments:   high_revenue_days, shipped_orders
        |
        v
Business metric (kind: metric, name: daily_sales_performance)
  measure:     daily_sales.total_daily_revenue
  ts:          daily_sales.order_date
  granularity: day
  dimensions:  daily_sales.region_name, daily_sales.category
```

A semantic model wraps one physical model and makes it queryable. A business metric takes a measure from a semantic model, adds a time dimension and default granularity, and becomes the primary interface for the Semantic Query API and dashboards.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/stage-2-productize/define-models-and-logic/semantic-models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.