---
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.

::: warning
The old values aren't cleared from memory until the cube is next loaded from disk, for example after a server restart. If an element with the same name is created again before then, its old values come back with it.

That makes an accidental delete recoverable by recreating the element within that time window.
:::

## 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.