---
url: /process-functions/dimension-set.md
description: >-
  Runs set instructions on a dimension and returns the elements they select, in
  order.
---

# dimension.set

Runs [set instructions](/set-instructions/in-scripts) on a dimension and returns the elements they select, in order. It's often used to fill a dropdown on a custom page.

```js
dimension.set(dimension, instructions, options)
```

## Parameters

| Parameter | Type | Description |
|---|---|---|
| `dimension` | `string` | The dimension's name or id. |
| `instructions` | `array` | The set instructions, run in order. Use `{ set: ["All Products"] }` to select elements, and plain strings such as `"expand-all"` for actions. It can't be empty. |
| `options` | `object` | Optional. `security`: `true` to list only what the signed-in user can see, or a user's id or email address for that user. `maxItems`: the most elements to return. A warning is written to the process log when the list is cut short. |

## Returns

The elements, in order. Each has:

* `name`: the element's name.
* `label`: the text to show. It's the alias when the instructions include `"use-alias:AliasName"`, otherwise the same as `name`.
* `hierarchy`: the hierarchy the element came from.
* `level`: how deep the element sits, for indenting a tree.
* `consolidation`: `true` when the element has children.

Returns `null` when the dimension, or an element or hierarchy in the instructions, can't be found. The reason is written to the process log.

## Examples

::: code-group

```js [regions.js]
// The signed-in user's regions
const regions = dimension.set("Region", [{ set: ["All Regions"] }, "expand-all"], { security: true });
```

```js [Result]
[
    { name: "All Regions", label: "All Regions", hierarchy: "Default", level: 0, consolidation: true },
    { name: "North", label: "North", hierarchy: "Default", level: 1, consolidation: false },
    { name: "South", label: "South", hierarchy: "Default", level: 1, consolidation: false }
]
```

:::

::: code-group

```js [products.js]
// Leaf products, labelled by their Description alias
const products = dimension.set("Product", [
    { set: ["All Products"] },
    "expand-all",
    "remove-all-consolidations",
    "use-alias:Description"
]);
```

```js [Result]
[
    { name: "P-100", label: "Standard Widget", hierarchy: "Default", level: 2, consolidation: false },
    { name: "P-200", label: "Deluxe Gadget", hierarchy: "Default", level: 2, consolidation: false }
]
```

:::

::: code-group

```js [accounts.js]
// The first 3 accounts a given user can see
const accounts = dimension.set("Account", [{ set: ["Profit and Loss"] }, "expand-all"], {
    security: "user@example.com",
    maxItems: 3
});
```

```js [Result]
[
    { name: "Profit and Loss", label: "Profit and Loss", hierarchy: "Default", level: 0, consolidation: true },
    { name: "Revenue", label: "Revenue", hierarchy: "Default", level: 1, consolidation: true },
    { name: "Sales", label: "Sales", hierarchy: "Default", level: 2, consolidation: false }
]
```

```text [Log]
dimension.set - Stopped at maxItems (3); the list is incomplete.
```

:::

## Related

* [Crosstab](/process-functions/cube-crosstab): uses the same set instructions to read cube data.
* [Set Instructions in Scripts](/set-instructions/in-scripts): the instructions it takes.