---
url: /process-functions/dimension-audit.md
description: >-
  Checks a dimension for orphaned elements, which are elements that no longer
  appear in any hierarchy, and optionally removes them.
---

# dimension.audit

Checks a dimension for orphaned elements, which are elements that no longer appear in any hierarchy, and optionally removes them.

Orphans are usually left behind when a hierarchy is restructured and an element isn't re-added anywhere. This is the scripted equivalent of the **Audit** button, and its **Remove Orphans** action, on a dimension's page in Gateway.

```js
dimension.audit(dimensionName, remove)
```

## Parameters

| Parameter | Type | Description |
|---|---|---|
| `dimensionName` | `string` | The dimension's name or id. |
| `remove` | `boolean` | `true` to remove every orphaned element found. `false` to only report them. |

## Returns

An object with `count`, the number of orphaned elements, and `orphans`, their names. Unlike most `dimension` functions it's an object, not a JSON string, so there's no need for `JSON.parse()`.

When the dimension can't be found, returns `{ "error": "can not find any dimension with that name or id." }` instead.

::: danger
Treat `dimension.audit(dimensionName, true)` as destructive. An orphan is removed from the dimension straight away, but any data held against it in cubes isn't dropped until the instance next restarts. An accidental removal can be undone by re-adding the element before that restart; after it, the data is gone for good.
:::

## Examples

```js
function begin() {
    let values = dimension.audit("Scenario", false);
    console.log(values);

    dimension.audit("Scenario", true); // removes the orphan(s) found above
    values = dimension.audit("Scenario", false);
    console.log(values);
}
```

```json
{"count":1, "orphans":["Budget"]}
{"count":0, "orphans":[]}
```

The first call reports one orphan, `Budget`, sitting in the `Scenario` dimension outside any hierarchy. The second call, with `remove` set to `true`, removes it, so the following report comes back with a count of zero and an empty orphans list.