The Semantic Layer is where you define your business metrics - Revenue, Gross Margin, Headcount, ARR, DSO - once, and use them as a single source of truth across Datarails. In this release, metrics defined in the Semantic Layer power Finance OS and AI agent queries, so every question returns the same number, calculated the same way.

When a metric definition changes, you update it in one place. Every consumer of that metric stays aligned automatically.

What the Semantic Layer gives you:

• A single, governed definition for each metric, used by Finance OS and AI agents.
• Time-aware calculations such as year-over-year, end-of-period, and days-based ratios, defined once and applied to any time period the user is viewing.
• Metrics that work across Actual, Budget, and Forecast scenarios from a single definition.
• Shared dimensions that connect related fields across different tables, so the same Department, Region, or Customer slice works on any metric.
• Access governed automatically from the data permissions already in place on the underlying tables.

Who uses the Semantic Layer 

The Semantic Layer serves two audiences with different goals. Both work from the same metric definitions, but the tasks they perform are different.

Builders

Builders are typically Data Managers, FP&A leads, or admins responsible for defining and maintaining metrics. Builders:

• Create base and calculated metrics.
• Define dimensions that are shared across tables.
• Choose how each metric behaves over time (Sum, Average, or End of period).
• Assign categories, formats, and descriptions.
• Decide which dimensions are suggested by default when the metric is analyzed.

Consumers

Consumers are analysts, managers, and business partners who use metrics to answer questions. Consumers:

• Browse and search metrics in the Metrics page.
• Use metrics in Finance OS and AI agent queries.
• Slice metrics by allowed dimensions and drill down into the detail.
• Compare metrics across Actual, Budget, and Forecast.

Core concepts 

Before you start, it helps to understand the building blocks of the Semantic Layer. Each concept has its own detailed article - this section is a quick orientation.

Metric

A named, reusable business definition such as Revenue, Gross Margin %, or Headcount. There are two kinds:

• Base metric - built directly from a raw data table. Example: Revenue pulled from your general ledger.
• Calculated metric - built from other metrics using a formula. Example: Gross Margin % = (Revenue − COGS) ÷ Revenue.

Dimension

A shared axis of analysis - Department, Region, Product, Customer - that you can slice metrics by. A single dimension can connect related fields from different tables, even when those fields are named differently, as long as they carry the same business meaning and values.

For example, a single “Department” dimension can map to the Cost Center column in your general ledger and to the Dept column in your headcount table. You define the mapping once, and the same Department slice works for Revenue, Headcount, and any other metric whose source table contains a department-like field.

Time aggregation

Every metric has a time aggregation that tells the Semantic Layer how to aggregate it across time periods:

• Sum - accumulates across periods. Used for flow metrics like Revenue, Expenses, and New Customers.
• Average - averaged across periods. Used for metrics such as average monthly headcount.
• End of period - closing balance at the end of the period. Used for snapshot metrics like Cash, AR, MRR, ARR, and Headcount.

Scenario

Metrics work across Actual, Budget, and Forecast. You define the metric once, and it runs against whichever scenario the user is viewing. Calculated metrics cannot mix scenarios inside a single formula.

Time-aware formulas

Calculated metrics can reference other metrics at different points in time - for example, the same metric one year ago, or its end-of-year closing value. This is what enables year-over-year variance, end-of-period ratios, and days-based KPIs like DSO and DPO.

Governance and access

You don’t share metrics manually. Access is derived automatically from the data permissions users already have on the underlying tables. If a user can see the underlying data, they can use the metric. If they can’t, the metric is hidden from them.

Metric owners can see the list of users who currently have access to a metric, along with anyone who is restricted and the reason - useful for confirming who can consume a metric and understanding why someone might not see it.

Video tour 

Watch this short Datarails University video for a guided tour of the Semantic Layer:

Learn more 

Dive into the detailed articles:

• Key concepts and terminology - a complete glossary of Semantic Layer terms.
• Creating a base metric - define a metric directly from a source table.
• Creating a calculated metric - build metrics from other metrics using the Formula Builder.
• Managing dimensions - create and map dimensions across tables.
• Permissions and access - who can use metrics and how access is governed.

Updated August 04, 2026 18:09