---
url: /process-functions/hierarchy-iteratechildren.md
description: Iterate through the children of an element in a hierarchy.
---

# hierarchy.iterateChildren 

Iterate through the children of an element in a hierarchy.

```js
hierarchy.iterateChildren(dimension, hierarchy, element, recursive);
```

#### Parameters

* `dimension` — The dimension in which the selected hierarchy exists.
* `hierarchy` — The identifier of the hierarchy to search.
* `element` — The identifier of the parent element. If blank or null, the root elements of the hierarchy are used.
* `recursive` — A boolean indicating whether to include all descendants (`true`) or only immediate children (`false`). `(optional)`

#### Returns

* `children` (iterable): An iterable view of child objects. Each item in the iteration represents a hierarchy element and contains the following properties:
  * `childIndex` (number): The zero-based index of this element within its parent's children.
  * `name` (string): The element name.
  * `fullName` (string): The fully-qualified name of the element within the hierarchy.
  * `childCount` (number): The number of immediate children this element has.
  * `depth` (number, optional): The depth of the element in the traversal (included when available).
  * `type` (string): The type of element. N for numeric, S for string.
  * `weight` (number): The weight of the element related to its parent element.

#### Example

```js
let children = hierarchy.iterateChildren("Time", "Default", "2026", true);

for (var child of children) {
    console.log(child);
}
```

#### Example child object:

```js
{
    "name": "2026 - Q1",
    "fullName": "Default»2026 - Q1",
    "childCount": 3,
    "childIndex": 0,
    "depth": 0,
    "type": "N",
    "weight": 1
}
```

:::warning Iteration Behavior

`hierarchy.iterateChildren` returns an **iterable view** over the hierarchy rather than a pre-built array. This design intentionally **avoids allocating memory** for a full list of children up front, which makes it more efficient for large hierarchies or streaming-style processing.

Because the iterator reads directly from the underlying hierarchy as you loop, there are a couple of important implications:

* **Low memory overhead** - items are produced on demand during iteration.
* **Live structure dependency** - if the hierarchy is **modified while you are iterating** (elements added, removed, reordered, or rebuilt), the iteration may:
  * Skip elements
  * Repeat elements
  * Produce inconsistent ordering
  * Or otherwise behave unpredictably

For most scenarios this is not an issue, but if you need a **stable snapshot** of the children, you should materialize the iterable into an array.

You can do this using either the spread operator **`...`** or `Array.from()`:

**Using spread**

```js
const children = [
    ...hierarchy.iterateChildren("Time", "Default", "2026", true),
];
```

**Using Array.from**

```js
const children = Array.from(
    hierarchy.iterateChildren("Time", "Default", "2026", true),
);
```

This creates a **copy in memory** at the cost of additional allocation, but guarantees that subsequent hierarchy changes will not affect your data.
:::