> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tarvah.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hierarchy Configuration
> Set up drill-down paths on your data to explore hierarchical relationships
Data often has natural levels — accounts belong to account groups, securities belong to sectors, cities belong to states. Hierarchy configuration lets you define these drill-down paths on a Virtual Data Mart so you can explore your data from the top level down to the details.
## When to use hierarchies
Use hierarchy configuration when your data has a parent-child or multi-level structure and you want to:
* Click on a summary value and see the breakdown underneath
* Navigate from broad categories down to individual records
* Build dashboards that let users explore data at their own pace
Link separate charts so clicking a value on one filters the next. Ideal for step-by-step exploration across dashboard panels.
Show all levels in a single visualization like a TreeMap or Sunburst. Ideal for seeing the full picture at a glance.
## Common examples
| Data domain | Drill-down path |
| ------------------- | ------------------------------------------------- |
| Accounts | Account Group → Account → Position |
| GICS classification | Sector → Industry Group → Industry → Sub-Industry |
| Issuers | Issuer → Security |
| Geography | Country → State → City |
| Organization | Division → Department → Team |
***
## Define a hierarchy on a VDM
Go to **DataBridge** → **Virtual Data Marts** and open the VDM you want to configure.
In the VDM editor, navigate to the **Hierarchy Configuration** section.
Click **Add Hierarchy** and give it a name (e.g., "Account Hierarchy") that describes the drill path.
Add levels from the broadest category to the most granular detail. For each level:
* **Name** — a label for this level (e.g., "Account Group")
* **Column** — pick from your VDM columns (e.g., `ACCT_GROUP_CD`)
* **Label column** (optional) — if the column is a code, pick a human-readable column (e.g., `ACCT_GROUP_NAME`)
The order matters. Level 0 is the top of the hierarchy and each subsequent level drills deeper.
Save the VDM. The hierarchy is now available when creating experiments from this VDM.
### Example: Account hierarchy
| Level | Name | Column | Label column |
| ----- | ------------- | --------------- | ----------------- |
| 0 | Account Group | `ACCT_GROUP_CD` | `ACCT_GROUP_NAME` |
| 1 | Account | `ACCT_CD` | `ACCT_NAME` |
| 2 | Position | `SEC_NAME` | — |
A user exploring this hierarchy would start by seeing account groups with aggregated totals, click into a group to see individual accounts, then click an account to see its positions.
***
## Import hierarchies from a BI model
If you are importing a BI semantic model into a VDM, hierarchies defined in the model are carried over automatically during import. You do not need to recreate them manually.
1. Go to **DataBridge** → **Virtual Data Marts** → **Import from BI**
2. Select the BI model and client
3. The import translates the model's hierarchy definitions into VDM hierarchy configuration
4. Review the imported hierarchies in the Hierarchy Configuration section
5. Save and publish
When you **sync** an existing VDM with its BI model, new hierarchies from the model are added without removing or modifying any hierarchies you have already defined.
***
## Use hierarchies in dashboards
Once a hierarchy is defined on a VDM, you can use it when building experiments and dashboards. There are two approaches depending on how you want users to interact with the data.
### Approach 1: Linked charts (progressive drill-down)
Create separate charts for each level and link them using chart interactions. When a user clicks a value on one chart, the next chart filters to show the details.
In your experiment, create one chart per hierarchy level:
* **Chart 1:** Bar chart grouped by `ACCT_GROUP_CD`, showing `SUM of MKT_VAL`
* **Chart 2:** Bar chart grouped by `ACCT_CD`, showing `SUM of MKT_VAL`
* **Chart 3:** Table grouped by `SEC_NAME`, showing `MKT_VAL` and `QTY`
On Chart 2, open the chart menu and set **Interaction** to Chart 1.
On Chart 3, set **Interaction** to Chart 2.
Click a bar on Chart 1 (e.g., "Fixed Income Group"). Chart 2 updates to show only accounts in that group. Click an account on Chart 2 — Chart 3 shows the positions in that account.
This approach works well for dashboards where you want to show multiple levels side-by-side and let users drill at their own pace.
### Approach 2: Hierarchy chart (all levels in one visualization)
Use a chart type that natively renders hierarchical data — the hierarchy levels are all visible at once inside a single chart.
Add a chart and choose a hierarchy-capable type such as **TreeMap**, **Sunburst**, or **Pack**.
Add your hierarchy columns as dimensions in order. For example:
* Dimension 1: `ACCT_GROUP_CD`
* Dimension 2: `ACCT_CD`
Add your measure (e.g., `SUM of MKT_VAL`).
The chart renders the parent level as outer sections and the child level nested inside. A TreeMap shows groups as large tiles with account tiles inside; a Sunburst shows groups as inner rings with accounts in outer rings.
### Which approach to choose
| Consideration | Linked charts | Hierarchy chart |
| ---------------- | ----------------------------- | -------------------------- |
| Number of levels | Any (2, 3, 4+) | Best for 2 levels |
| User interaction | Click to progressively reveal | All levels visible at once |
| Dashboard layout | Multiple panels | Single panel |
| Best for | Detailed exploration | Overview and proportions |
You can combine both approaches in the same dashboard — use a Sunburst for an overview panel and linked bar charts for detailed exploration.
***
## Supported hierarchy chart types
These chart types display multi-level data within a single visualization:
| Chart type | Best for |
| ------------------------------- | ---------------------------------------------------- |
| TreeMap | Proportional area comparison across levels |
| Sunburst | Radial breakdown showing part-to-whole relationships |
| Pack | Bubble nesting to show containment |
| Voronoi TreeMap | Space-efficient alternative to TreeMap |
| Tree | Organizational or structural relationships |
| Partition (horizontal/vertical) | Level-by-level breakdown in a linear layout |
| Grouped Column | Side-by-side comparison across 2-3 levels |
For drill paths with more than 2 levels, use the **linked charts** approach.
***
## Import via SDK
When creating dashboards through the SDK, use hierarchy chart types and order your `dimensions` array from broadest to most granular:
```json theme={null}
{
"name": "Account Position Dashboard",
"dataSource": {
"dbId": "D2026A00002",
"vdmId": "VDM2026A00001",
"connType": "VDM"
},
"charts": [
{
"title": "Market Value by Account Group",
"type": "treemap",
"measures": [{ "field": "MKT_VAL", "aggregation": "sum" }],
"dimensions": ["ACCT_GROUP_CD", "ACCT_CD"]
}
]
}
```
The first dimension becomes the parent level and subsequent dimensions become child levels in the visualization.
For linked-chart dashboards, create separate charts in sections and set up interactions after import through the experiment editor.