Dimensions are the shared business axes you slice metrics by - Department, Region, Product, Customer. A single dimension can connect related fields from different data tables, even when those fields are named differently, as long as they carry the same meaning and values. Defined once, a dimension can be reused across every metric whose source table contains a matching field.

This article walks through creating and managing dimensions. For how dimensions are used inside a metric, see Creating a base metric and Creating a calculated metric.

Before you start 

• Permission to manage dimensions. The minimum role required to create, edit, and delete dimensions is Data Manager. Roles are assigned by your Datarails admin.
• Access to the source tables whose fields you want to include in the dimension. You can only map fields from tables you have access to.

Open the Dimensions tab 

1. From the left navigation, open the Setup section and select Metrics & dimensions.
2. Switch to the Dimensions tab.

The Dimensions tab lists every dimension defined in your workspace, with the source tables it’s mapped to and the metrics that use it. Filter by Source tables or Used in metrics, or search by name to find a specific dimension.

Create a dimension 

Open the Create dimension form

1. On the Dimensions tab, click + New dimension.
2. The Create new dimension dialog opens with three parts: a Name field, a Tables & fields mapping section, and a VALUES PREVIEW panel on the right.

Name the dimension

Enter a Name that your team will recognize. Use the business name (Department, Region, Product), not a technical column name. Names must be unique across the workspace - if you reuse a name, the dialog shows the inline error “This name is already in use. Please choose a different name.” and the Create button stays disabled.

Map fields across tables

In the Tables & fields section you tell the Semantic Layer which column in each table represents this dimension. The same dimension can connect fields from different tables - even when those fields have different names - as long as they carry the same business meaning and values.

1. From the Table dropdown on the first row, select a source table - for example, Financials.
2. From the Field dropdown, select the column in that table that represents the dimension - for example, Cost Center for a Department dimension.
3. Click + Add table to map the dimension to another table.
4. On the new row, pick the next table (for example, Headcount) and the column that represents the same dimension there (for example, Dept). The fields don’t have to share a name - only their meaning and values.
5. Repeat for any additional tables that contain a matching field. To remove a row, click the trash icon on the right.

Tip: When you add another table whose schema includes a column with the same name as the field in your first row, the Semantic Layer pre-selects it as a smart default. You can change the selection if a different field is the right match.

Review the values preview

As soon as a Table and Field are mapped, the VALUES PREVIEW panel populates with a sample of distinct values the dimension contains. Each value carries a badge indicating where it comes from:

• Source-table badge (e.g., Financials, Headcount) - the value exists in only that table.
• All tables - the value exists in every table the dimension is mapped to.

Use the preview to sanity-check your mapping before saving. If you see unexpected values, missing values, or a different distribution than you expected, double-check that you picked the right field on each table.

Heads-up about partial values: If some values appear in only some of the mapped tables, the preview shows the warning “Values appearing in only some tables may return incomplete results.” This is a signal that the dimension may behave inconsistently when used to slice metrics built from different tables - review the mapping or the underlying data to confirm it’s what you intend.

Save the dimension

1. Once the Name is set and at least one Table+Field row is fully mapped, the Create button becomes active.
2. Click Create. The dialog closes and the new dimension appears in the Dimensions list, ready to be used in any metric whose source table contains a matching field.

If you close the dialog with unsaved changes, the Semantic Layer asks: “You have unsaved changes. If you leave now, your changes will be lost. Are you sure you want to exit?” Click Cancel to keep editing or exit to discard your changes.

Edit a dimension 

You can update a dimension’s name and mappings at any time. Changes apply immediately to every metric that uses the dimension, so be deliberate when removing or replacing field mappings.

1. On the Dimensions tab, click the three-dots menu (⋮) next to the dimension and choose Edit.
2. Update the Name, add or remove rows in the Tables & fields section, or change the field selected for any table.
3. Click Save.

Editing across tables you can’t access: When a dimension is mapped to a table you don’t have access to, the row for that table is shown in a read-only state so you can see the full definition without being able to change it. You can still add, remove, or change rows for tables you do have access to.

Delete a dimension 

1. On the Dimensions tab, click the three-dots menu (⋮) next to the dimension and choose Delete.
2. Confirm the deletion.

A dimension that’s currently used by one or more metrics cannot be deleted. Remove the dimension from those metrics first, then delete.

Related articles 

• Key concepts and terminology
• Creating a base metric
• Creating a calculated metric
• Permissions and access

Updated August 04, 2026 18:50