---
url: /process-functions/dimension-audit.md
description: >-
  Reports, or removes, orphaned elements in a dimension - elements that still
  exist in the dimension but no longer appear in any hierarchy.
---

# dimension.audit

Checks a dimension for **orphaned elements** - elements that still exist in the dimension but no longer appear in any hierarchy, typically left behind after a hierarchy was restructured and the element wasn't re-added anywhere. Returns the orphan count and their names, and optionally removes them. This is the scripted equivalent of the **Audit** button (and its **Remove Orphans** action) on a dimension's page in Gateway.

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

#### Parameters

* `dimension_name` - Name of the dimension to audit.
* `remove` - if `true`, removes every orphaned element found. If `false`, only reports them without changing anything.

#### Example

```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);
}
```

##### Example output

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

::: tip
Unlike most other `dimension.*` functions (`elements`, `hierarchies`, `aliases`, `list`), `dimension.audit` returns a native object directly, not a JSON string - no `JSON.parse` needed to read `.count` or `.orphans`.
:::

::: warning Failure behavior
Returns the object `{"error":"can not find any dimension with that name or id."}` when:

* `dimension_name` doesn't exist

Not thrown as an exception, and still a native object (not a JSON string) - check for an `error` property rather than `count`/`orphans`.
:::

::: danger
Treat `dimension.audit(dimension_name, true)` as destructive. An orphan is removed from the dimension's element list immediately, but any data held against it in cubes isn't dropped until the Instance is next restarted - so an accidental removal can still be undone by re-adding the element before that restart, but once the Instance restarts, that data is gone for good. Only run it with `remove: true` when there's a specific reason to clean up the dimension and no important data sits against the orphaned elements.
:::