This article defines the foundational terms you’ll see throughout the Semantic Layer. Use it as a quick reference while you’re building or consuming metrics. Where a term has its own dedicated article, you’ll find a link to it.
Jump to a section:
Metrics
Metric
A reusable, named business definition such as Revenue, Gross Margin %, or Headcount. A metric carries its own logic and time behavior, and is used as a single source of truth wherever it appears.
Base metric
A metric built directly from a raw data table. You choose the source table, the value field, the date field, and any relevant filters; the Semantic Layer aggregates the data accordingly. Example: Revenue read from your general ledger, filtered to revenue accounts only.
Calculated metric
A metric built from other metrics using a formula. Calculated metrics use arithmetic operators and can reference other metrics at different points in time. Example: Gross Margin % = (Revenue − COGS) ÷ Revenue.
Category
A user-defined grouping that helps you organize metrics in the Metrics page, such as P&L, Workforce, or SaaS KPIs.
Dimensions
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.
Field mapping
The connection between a dimension and a specific column in a source table. A dimension can be mapped to one field per table, and the same dimension can map to differently named fields across multiple tables.
Primary Analysis Dimensions
The set of dimensions chosen for a specific metric - the slices that are most meaningful for analyzing it. Each metric has its own Primary Analysis Dimensions, selected by the builder when the metric is defined, and used as the default breakdowns when the metric is consumed.
Scenarios
Scenario
A default dimension that’s always applied to every metric, with values like Actual, Budget, and Forecast (plus any sub-scenarios such as different budget cycles or forecast versions). The Semantic Layer automatically calculates each metric for every scenario and sub-scenario in your data - builders don’t need to set this up per metric.
Value calculation
Value calculation
How a metric reduces source rows to a single value within a period. The four options are Sum, Count, Cumulative Sum, and Cumulative Count.
Sum
Adds up the numeric values in the source field for the period.
Count
Counts the rows in the source for the period.
Cumulative Sum
Running total from the earliest data point through the period being viewed. Use for balance-style metrics built from delta sources, such as ARR balance, cash balance, or headcount.
Cumulative Count
Running count of rows from the earliest data point through the period being viewed. Use for cumulative tallies such as total customers ever onboarded.
Time aggregation
Time aggregation
The setting that tells the Semantic Layer how a metric’s values combine across time periods - for example, when a metric defined at a monthly grain is viewed at the quarterly or annual level. The three options are Sum, Average, and End of period.
Time aggregation is set on every base metric when it’s created. A calculated metric doesn’t have its own time aggregation setting - it inherits the behavior of each metric it references, so every operand in the formula aggregates according to its own definition.
Time aggregation is applied at consumption time: when a metric is viewed in a wider period, the Semantic Layer combines the underlying values according to this setting. Choosing the correct time aggregation is what makes the same metric definition produce the right number in monthly, quarterly, and annual views.
Sum
Values accumulate across periods. Used for metrics whose totals are meaningful over time, such as Revenue, Expenses, or New Customers.
Average
Values are averaged across periods. Used for metrics like average monthly headcount, where the relevant aggregate is a mean rather than a total.
End of period
The closing value at the end of the period is used. Used for metrics like Cash, AR, MRR, ARR, and Headcount, where what matters is the balance at a point in time, not the total of daily values.
Time-aware formulas
Time-aware formula
A calculated metric that references another metric at a different point in time - for example, the same metric a number of periods ago, or its end-of-period value. Time-aware formulas power KPIs such as:
- DSO (Days Sales Outstanding) - combines Accounts Receivable, Revenue, and Days in period.
- End-of-year cash balance - references Cash at the end of the prior period.
- Lagged CAC - divides new customers in the current period by marketing spend from a prior period, accounting for the lag between marketing investment and customer conversion.
- Year-over-year variance - compares the current value of a metric to its value one year earlier.
Days in period
A built-in value equal to the number of calendar days in the period the user is currently viewing. The value is resolved at consumption time based on the period in view - 31 for January, 90 or 91 for Q1, 365 or 366 for a full year - so the same formula adapts automatically to whichever period is being displayed.
Used in days-based formulas like DSO = (AR ÷ Revenue) × Days in period.
Related articles
- What is the Semantic Layer?
- Creating a base metric
- Creating a calculated metric
- Time-aware formulas
- Time aggregation
- Managing dimensions
© Datarails Ltd. All rights reserved.
Updated
Comments
0 comments
Please sign in to leave a comment.