A base metric is a reusable business definition built directly from one of your source tables - for example, Revenue read from the Financials table, or Headcount read from a Headcount table. Once defined, the metric becomes a single source of truth that you and your team can use anywhere in the Semantic Layer.

This article walks through creating a base metric from start to finish. For metrics built from other metrics using a formula, see Creating a calculated metric.

Before you start 

To create a base metric, you need:

• Permission to manage metrics. The minimum role required to create and edit metrics is Data Manager. Roles are assigned by your Datarails admin.
• Access to the source table that contains the data you want the metric to read from.
• A clear definition of what the metric represents, how it should aggregate over time, and any filters that should apply.

Open the new metric editor 

1. From the left navigation, open the Setup section and select Metrics & dimensions. Make sure the Metrics tab is selected.
2. Click + New metric. The New metric editor opens.
3. Select the Base metric tab (“Created from raw data”).

Define the data source 

In the editor, the Metric definition box is where you tell the Semantic Layer which data the metric reads from.

1. Click the Metric definition box (or Click to define metric). The Create new base metric dialog opens.
2. From the Data table dropdown, select the source table that contains the raw data - for example, Financials.
3. From the field list on the left, drag fields into the drop zones on the right:
   • Date field - the column the Semantic Layer uses to place each row in time. Drag one date-type field here.
   • Value - the column whose values the metric reads. Drag one field here.
   • Filters - optional. Drag any number of fields here to restrict which rows are included - for example, an Account group L2 filter to limit a Revenue metric to revenue accounts only.
4. The Preview on the right updates as soon as the Date field and Value drop zones are filled. By default it shows Actuals only - toggle Show Actuals only off if you want to see all scenarios.
5. Click Apply.

Filters are part of the metric’s definition. They apply every time the metric is used, not just in the current view.

After applying, the editor shows a summary of the definition - for example, Sum of Amount from Financials, with the active filter (Account group L2 = Revenue) and the date field (Reporting month) listed underneath.

Choose the value calculation 

The Value calculation tells the Semantic Layer how to reduce the source rows in a period to a single value. Pick one of four:

• Sum - adds up the numeric values in the source field. Numeric fields only.
• Count - counts the rows in the source. Works on any field type.
• Cumulative Sum - a running total from the earliest data point through the period being viewed. Use for running totals like ARR or cumulative bookings. Numeric fields only.
• Cumulative Count - a running count from the earliest data point through the period being viewed. Use for running counts such as the total number of customers acquired since launch.

When you drag a field into the Value section, the Semantic Layer picks a default value calculation based on the field type: Sum for numeric fields and Count for non-numeric fields. Change the value calculation by selecting a different option from the dropdown.

Field-type rules:

• Sum and Cumulative Sum work only on numeric fields (Whole Number, Decimal Number). They appear in the dropdown but are disabled when the selected field is non-numeric.
• Count and Cumulative Count work on any field type, including text, dates, and true/false values.

Set the time aggregation 

The Time aggregation setting controls how the metric’s values are rolled up over time. Choose one of the three options:

• Sum - adds all values in the period.
• End of period - uses the last value in the period.
• Average - calculates the average value in the period.

Choosing the right time aggregation

A simple test: ask whether it makes sense to add the metric across two periods. If “January Revenue + February Revenue” gives a meaningful number, use Sum. If “January Headcount + February Headcount” is nonsense (you don’t add headcount month-to-month), use End of period.

Use Average when neither sum nor snapshot is meaningful and you want the typical value during the period - for example, the average daily cash balance during the month.

Use Sum for metrics that accumulate over time:

• Revenue
• Expenses, COGS, Operating expenses
• New customers, churned customers
• Units sold, hours logged
• Cash inflow, cash outflow

Use End of period for balances or counts captured at a point in time:

• Cash balance
• Accounts Receivable, Accounts Payable
• Headcount
• MRR, ARR
• Inventory on hand
• Open opportunities

Use Average for metrics that represent a typical value across the period:

• Average daily cash balance
• Average AR balance during the period
• Average headcount during a hiring ramp
• Average inventory level

Why this matters: The Semantic Layer can’t tell whether your data should be added, snapshotted, or averaged just by looking at it. You have to declare it so the system knows what to do when consumers view the metric at a wider time grain than it was recorded at - for example, a daily metric viewed quarterly, or a monthly metric viewed annually.

Time aggregation defaults and compatibility

Each value calculation has a default time aggregation, applied when you haven’t changed the time aggregation yourself:

• Sum and Count default to Sum.
• Cumulative Sum and Cumulative Count default to End of period.

For cumulative value calculations, the Sum time aggregation isn’t available.

When you change the value calculation on an existing metric, the time aggregation is preserved if it’s still valid for the new value calculation. If not, the new value calculation’s default is applied.

Add dimensions 

Dimensions are the slices users can break the metric down by - for example, Region, Department, or Country.

1. Click + Add dimensions.
2. In the dropdown, check the dimensions you want to include for this metric. The list shows only the dimensions that are connected to the metric’s source table - dimensions that aren’t mapped to that table can’t be used here. The Preview updates instantly to show breakdowns by the selected dimensions.
3. To create or edit dimensions, click Manage dimensions at the bottom of the dropdown. See Managing dimensions for details.

The dimensions you select become the metric’s Primary Analysis Dimensions - the default breakdowns shown when the metric is consumed.

Name and describe the metric 

1. Enter a Name that your team will recognize (for example, Revenue). Use the business name, not a technical column name.
2. The Semantic Layer automatically generates a draft Description based on the metric’s definition. The sparkle icon next to Description - with the tooltip Generated by AI - indicates the description came from AI.
3. Review the description. Edit or replace it to match how your team actually uses the metric. Once you edit the description, the AI indicator updates to show the description is now yours.

A clear, business-language description helps consumers understand what the metric measures and when to use it. We recommend reviewing the AI-generated draft and adjusting it for your team’s vocabulary.

Choose a category 

1. Click the Category field and select an existing category from the dropdown - for example, P&L, Workforce, or SaaS KPIs.
2. To create a new one, click + Add new category at the top of the dropdown.

Category is how your team finds metrics quickly when browsing the Metrics & dimensions page. It’s also useful metadata for AI agents and other consumption surfaces, helping them understand which metrics belong together.

Choose a format 

The Format setting controls how the metric’s result is displayed by default wherever the metric is used - in Finance OS, AI agent answers, and any other consumption surface. Choose the format that matches the metric’s real-world meaning:

• Currency - for monetary metrics like Revenue, Expenses, or Cash.
• Percentage - for ratio metrics like Gross Margin % or Growth Rate.
• Decimal - for numeric metrics that aren’t money or percentages, like Headcount or Customer count.

You can also adjust formatting details such as decimal places and thousand separators. The format you choose here is the default for every consumer of the metric.

Save the metric 

1. Review the editor for any validation messages.
2. Click Save.
3. The metric appears in the Metrics & dimensions page and is ready to use.

View a metric’s definition 

Anyone with access to a metric can open its definition without editing it - useful for confirming exactly how a metric is calculated before using it.

1. On the Metrics & dimensions page, locate the metric you want to inspect.
2. Click the three-dots menu (⋮) next to the metric and choose See details to open the read-only view.
3. Review the metric definition, time aggregation, dimensions, and description. Close the view when you’re done.

Edit a base metric 

You can change a metric’s definition at any time. Edits take effect for every consumer of the metric, so be deliberate when changing fields that affect the metric’s values.

1. On the Metrics & dimensions page, locate the metric you want to edit.
2. Click the three-dots menu (⋮) next to the metric and choose Edit.
3. Update the fields you need to change.
4. Click Save.

Changing the data source, date field, value, filters, or time aggregation of a metric that’s already in use can change the values seen by every consumer downstream. The Semantic Layer asks you to confirm before saving these changes.

Delete a base metric 

1. On the Metrics & dimensions page, locate the metric you want to delete.
2. Click the three-dots menu (⋮) next to the metric and choose Delete.
3. Confirm the deletion.

A metric that’s referenced by another metric cannot be deleted. Remove the reference from the dependent metric first, then delete.

Related articles 

• Key concepts and terminology
• Creating a calculated metric
• Managing dimensions
• Permissions and access

Updated August 04, 2026 18:25