Dimensions

Every metric needs something to be grouped by, and that is what dimensions are. In a Celiq node they live under the attributes: key in CML, but the product surfaces them everywhere as Dimensions — the read-only Context Studio Dimensions tab, the node badges, and Discover's group-by picker all use that word. This page covers how dimensions are defined, the small naming drift between CML and the UI, and how the saver decides what counts as a dimension versus a metric.

Overview

A dimension is one entry in a node's attributes array. Each entry describes a single warehouse column you can group, filter, or split a chart by. A dimension carries no aggregation — it is a raw column value such as a date, a region label, or a status string. Metrics (SUM, COUNT, AVG, …) are the opposite: they roll many rows up into one number. Dimensions and metrics together make a node useful — metrics are the numbers, dimensions are the axes you read them along.

A single dimension definition supports these properties:

When to use it

Add a dimension to a node whenever you want to be able to:

• Group by it — split a chart or table into one row/series per value (revenue by region).
• Filter by it — narrow results to specific values (order_status = delivered).
• Trend over time — date dimensions with time_grains let you switch a chart between daily, weekly, and monthly buckets.
• Give Orion an axis — the AI layer reads dimension name, description, and values to understand what it can slice your metrics by.

If the field is something you would aggregate rather than group by — a revenue total, an order count — it belongs under metrics, not here. See Metrics.

Concepts

Getting started

Prerequisites:

• A workspace with at least one node modelled in Forge.
• The Weaver or Luminary role to author or edit a node's CML.

To browse existing dimensions:

1. Open Context Studio from the main navigation.
2. Select the Dimensions tab.
3. You will see every dimension across all nodes, grouped by node, with a filter box to search by field or node name.

To author dimensions, open Forge and edit the node's CML directly.

Step-by-step

Examples

A node from ecommerce.celiq defining its dimensions. Note the date dimension's time_grains and the enumerated values on region and order_status:

tables:
  - name: fct_orders
    physical_table: DW_PROD.OMS.FCT_ORDERS
    description: One row per order. Primary fact table for revenue reporting.

    dimensions:
      - name: order_date
        column: ORDER_DATE
        type: date
        description: Date the order was placed (not shipped or delivered)
        time_grains: [day, week, month, quarter, year]

      - name: region
        column: SHIPPING_REGION
        type: string
        description: Geographic region of the shipping address
        values: [US, EU, APAC, LATAM]

      - name: order_status
        column: STATUS
        type: string
        description: Current order status
        values: [pending, confirmed, shipped, delivered, cancelled, returned]

When this saves, the normalizer renames the dimensions: key to the canonical attributes:, leaving the entries unchanged. Context Studio then flattens each attribute into a flat row. For order_date it returns:

{
  "node": "fct_orders",
  "name": "order_date",
  "label": "order_date",
  "type": "date",
  "column": "ORDER_DATE"
}

Because no label was set, the response falls back to name, and the Dimensions tab shows order_date with ORDER_DATE as its column and a date type badge.

Best practices

• Always set a type. It defaults to string. Mark dates as date and numeric group-by columns as integer so charts, filters, and time-grain controls behave correctly.
• Give every dimension a description. Orion reads these to decide how to slice your metrics, and readers rely on them in Context Studio.
• Declare time_grains on date dimensions. Without them, a date dimension has no documented grains to roll up to.
• Use values for low-cardinality fields. Listing the regions, channels, or statuses a column holds documents the data and helps Orion reason about it.
• Add a column whenever it differs from name. Use a clean, readable name for the dimension and point column at the real warehouse column (e.g. name: region, column: SHIPPING_REGION).

Tips

Common mistakes

• Forgetting type on a date. A date left as the default string will not behave as a time dimension. Set type: date and add time_grains.
• Expecting dimensions to be editable in Context Studio. The Dimensions tab is read-only. All authoring happens in Forge — the tab's empty state even points you there: "Add attribute fields to nodes in Forge."
• Assuming column defaults to something else. If you omit column, it defaults to name. When your warehouse column name differs, you must set column explicitly or the query will reference the wrong column.

Troubleshooting

Related pages

• Metrics
• Drill paths
• Filter mappings
• Semantic layer overview
• Forge