hierarchy.offset

Returns the element a set number of positions before or after another element in a hierarchy.

• A top-level element moves through the top-level elements.
• A parent below the top level moves through its siblings under the same parent.
• A leaf element under a parent isn't found, and returns "Error: Element not found …".

hierarchy.offset(dimension, hierarchy, element, offset)

Parameters

Parameter	Type	Description
dimension	string	The dimension's name or id.
hierarchy	string	The hierarchy's name or id.
element	string	The element to start from.
offset	number	How many positions to move. Positive moves forward and negative moves back.

Returns

string

The element's name, or a message starting with "Error:" when it can't be found or the offset goes past the first or last element it can move through.

Examples

Move between elements

offset.js

console.log(hierarchy.offset("Time", "Default", "FY2025", 1));
console.log(hierarchy.offset("Time", "Default", "Memo", -2));
console.log(hierarchy.offset("Time", "Default", "Q1", 1));
console.log(hierarchy.offset("Time", "Default", "Q2", 1));
console.log(hierarchy.offset("Time", "Default", "Jan", 1));

Hierarchy

FY2025
	Q1
		Jan
		Feb
		Mar
	Q2
		Apr
		May
		Jun
FY2026
	Q1-26
		Jan26
Memo

Result

FY2026
FY2025
Q2
Error: offset is beyond the length of this hierarchy.
Error: Element not found 'Jan'.

FY2025 and Memo move through the top-level elements. Q1 moves to its sibling Q2, but Q2 has no sibling after it. Jan is a leaf under a parent, so it isn't found.