Type: Function

Function: DIMENSION

Syntax: DIMENSION(position) or DIMENSION(label)

Description: Returns the value of another dimension of the same insight, so that its formula does not have to be written twice. The dimension is given by its position, starting at 1 (DIMENSION(1) is the first dimension), or by its label when the query names its dimensions (DIMENSION("labels")). Labels are matched in any case.

In the insight designer, refer to a dimension by its position: DIMENSION(1) is the dimension shown as Dimension 1. Labels are for queries sent through the Keypup API or the MCP server, which name each dimension.

DIMENSION can be used in other dimensions, in metrics and in filters.

A position follows the dimension's place, not the dimension. Moving dimensions around, or removing one, changes the dimension DIMENSION(2) refers to. A dimension cannot refer to itself, directly or through other dimensions.

In another dimension

DIMENSION is the other dimension's formula as written, so a dimension can be built on another: a year from a month, a "Long" or "Short" bucket from a duration in days, a prefix of each label. A dimension can refer to any dimension of the insight, before or after it.

A dimension that is only DIMENSION(1) is sorted and filled in like dimension 1: a copy of a month dimension lists every month from the first record to the last.
A dimension built on a FLATTEN dimension can transform each value, as CONCAT("#", DIMENSION(1)) does, but cannot test it in a condition such as IF. FLATTEN turns one record into several, and a value that produces records cannot be tested in a condition. The same formula with the FLATTEN written out fails for the same reason.
When a dimension is built on another, an insight that fills in missing values can show combinations that never occur, with empty metrics, such as a year next to a month of another year.

In a metric

DIMENSION is the value of the group the metric is calculated for. A metric is calculated once per group of dimension values, so the value is the same for every record of the group. It lets a metric depend on its group, for example to weigh it or to label it.

In a filter

DIMENSION is the other dimension's formula as written, and a FLATTEN in it does nothing, as anywhere in a filter. A filter keeps or drops whole records, before they are split into one record per value, so it sees each record's full list. With FLATTEN(label_names) as dimension 1, DIMENSION(1) is therefore the list of labels of each record in a filter. Filter it with list functions such as CONTAINS, not with ==, which compares a single value.

In the insight designer, a formula dimension already appears in the filters as Dimension 1, Dimension 2 and so on, which is the simplest way to filter on it.

Sample usage:

With YEAR_MONTH(created_at) as dimension 1, LEFT(DIMENSION(1), 4) as dimension 2 gives the year of each month.
With ROUND(TIMELINE_DURATION(workflow_timeline, "In Progress") / 86400) as dimension 1, IF(DIMENSION(1) > 5, "Long", "Short") as dimension 2 sorts the records into long and short ones.
With FLATTEN(label_names) as dimension 1, LEFT(DIMENSION(1), 3) as dimension 2 gives the first three letters of each label, next to the label.
With FLATTEN(label_names) as dimension 1, IF(DIMENSION(1) == "bug", COUNT() * 2, COUNT()) as metric counts the bugs twice.
With YEAR_MONTH(created_at) as dimension 1 and state as dimension 2, CONCAT(DIMENSION(1), " ", DIMENSION(2)) as metric labels each group, such as 2026-10 OPEN.
With FLATTEN(label_names) as dimension 1, CONTAINS(DIMENSION(1), ["bug", "epic"]) as filter keeps the records that have the label bug or epic.
In a query sent through the API with a dimension labelled days, IF(DIMENSION("days") > 5, "Long", "Short") refers to it by its label.