TreeMap

Overview

• Type: One-dimensional area-based hierarchical chart
• Dimensions: Proportional rectangles sized by measure value
• Use cases: Show hierarchical data, display multi-level breakdowns, visualize large datasets with drill-down, compare proportions across categories
• Special features: Supports multi-level drill-down, area size represents percentage of total (50% of total = 50% of area)
• Visual: Nested rectangles where size represents value, enabling visual comparison of proportions

The image shows a treemap displaying revenue by division, customer group, and customer number, with rectangle sizes proportional to revenue amounts.

The second image shows the same treemap with multi-level filtering enabled, allowing users to drill down from division to customer group to customer number.

Quickstart

To create a TreeMap, initialize the graph with hierarchical split element, add an axis, and use addGraphData with chart_type: "treemap".

$olap.addGraph("2","Revenue ?period.getYear()","[division]:[customer_group]:[customer_number]","[invoice_year]=?period.getYear()","0");
$olap.addGraphAxis("2","1","Amount","");
$olap.addGraphData("2","1","Revenue","[division]:[customer_group]:[customer_number]","sum([invoiced_amount_dcur])","treemap","","","","M");

Start here

Replace:

• "2" with your graph ID
• "[division]:[customer_group]:[customer_number]" with your hierarchical columns (use : to separate levels)
• "sum([invoiced_amount_dcur])" with your measure
• Ensure the same hierarchy appears in both addGraph split element and addGraphData series

This produces a treemap where rectangle sizes represent revenue, with drill-down capability from division → customer group → customer number.

Series setup

TreeMaps use hierarchical series columns separated by colons. The hierarchy must match in both addGraph and addGraphData.

Required setup:

$olap.addGraph("graph_id", "Title", "[level1]:[level2]:[level3]", "filter","0");
$olap.addGraphAxis("graph_id","axis_id","Label","");
$olap.addGraphData("graph_id","axis_id","Label", "[level1]:[level2]:[level3]", "measure", "treemap","","","","M");

Key points:

• Use colon : to separate hierarchy levels: "[division]:[customer_group]"
• Same hierarchy must appear in both addGraph split element and addGraphData series
• Each level enables drill-down filtering
• Order matters: first level = top level, last level = most detailed

Example - Two levels:

$olap.addGraph("1", "Sales by Region", "[region]:[country]", "","0");
$olap.addGraphData("1","1","Sales", "[region]:[country]", "sum([sales])", "treemap","","","","M");

Example - Three levels:

$olap.addGraph("1", "Revenue Breakdown", "[division]:[product_group]:[product]", "","0");
$olap.addGraphData("1","1","Revenue", "[division]:[product_group]:[product]", "sum([revenue])", "treemap","","","","M");

Critical

The hierarchy in addGraph split element MUST match the hierarchy in addGraphData series. If they differ, drill-down won’t work correctly.

Data series

Add data using addGraphData with chart_type: "treemap". The series column defines the hierarchy.

Syntax:

$olap.addGraphData(
    "graph_id",
    "axis_id",
    "dataseries_label",
    "series",                    // Hierarchical: "[level1]:[level2]:[level3]"
    "measure",
    "treemap",
    "",
    "filter",
    "limit",
    "orderby"
)

Parameters:

Parameter	Required	Description	Example
graph_id	Yes	Unique graph identifier	"2"
axis_id	Yes	The axis ID	"1"
dataseries_label	Yes	Label for the series	"Revenue"
series	Yes	Hierarchical columns separated by :	"[division]:[customer_group]"
measure	Yes	Value determining rectangle size	"sum([amount])"
chart_type	Yes	Must be "treemap"	"treemap"
aggregation	No	Not used (use "")	""
filter	No	Additional filter	"[year] = 2024"
limit	No	Limit items shown	"20"
orderby	No	Sort method. "M" for largest first	"M"

Example - Single level:

$olap.addGraph("1", "Sales by Product", "[product]", "","0");
$olap.addGraphData("1","1","Sales", "[product]", "sum([sales])", "treemap","","","","M");

Example - Multi-level with filter:

$olap.addGraph("2","Revenue","[division]:[customer_group]:[customer_number]","[invoice_year]=?period.getYear()","0");
$olap.addGraphData("2","1","Revenue","[division]:[customer_group]:[customer_number]","sum([invoiced_amount_dcur])","treemap","","","","M");

Note

TreeMaps are sensitive to NULL values. Always exclude NULLs in your filter: "[division] IS NOT NULL AND [customer_group] IS NOT NULL".

Size and layout

Control responsive width using setGraphSize. TreeMaps benefit from larger sizes to show detail.

$olap.setGraphSize("graph_id", "XS12", "SM6", "MD6", "LG6")

Recommended sizes:

• Medium: "XS12", "SM6", "MD6", "LG6" (half width)
• Large: "XS12", "SM8", "MD8", "LG8" (two-thirds width)
• Full: "XS12", "SM12", "MD12", "LG12" (full width)

Tip

TreeMaps with multiple levels need space to show nested rectangles clearly. Use at least SM6/MD6 for multi-level treemaps.

Common patterns

Single level treemap

Simple proportional comparison:

$olap.addGraph("1", "Sales by Region", "[region]", "","0");
$olap.addGraphAxis("1","1","Amount","");
$olap.addGraphData("1","1","Sales", "[region]", "sum([sales])", "treemap","","","","M");

Multi-level drill-down

Enable hierarchical exploration:

$olap.addGraph("1", "Revenue Hierarchy", "[division]:[department]:[product]", "","0");
$olap.addGraphData("1","1","Revenue", "[division]:[department]:[product]", "sum([revenue])", "treemap","","","","M");

Filtered treemap

Focus on specific subset:

$olap.addGraph("1", "Q4 Sales", "[category]:[subcategory]", "[quarter] = 4 AND [year] = 2024","0");
$olap.addGraphData("1","1","Sales", "[category]:[subcategory]", "sum([sales])", "treemap","","","","M");

Top N items

Show only largest categories:

$olap.addGraphData("1","1","Revenue", "[product]", "sum([revenue])", "treemap","","","10","M");

Time-based treemap

Show breakdown for specific period:

$olap.addGraph("1", "2024 Revenue", "[category]:[item]", "[year] = 2024","0");
$olap.addGraphData("1","1","Revenue", "[category]:[item]", "sum([revenue])", "treemap","","","","M");

Troubleshooting

Treemap not showing

• Check: Ensure chart_type is exactly "treemap" (lowercase)
• Check: Verify hierarchy matches in both addGraph and addGraphData
• Check: Ensure measure returns numeric values
• Check: TreeMap can only be built on the report’s main data source (not alternative sources)

Drill-down not working

• Issue: Clicking doesn’t show next level
• Fix: Hierarchy in addGraph split element must match addGraphData series exactly
• Fix: Both must use same column order: "[level1]:[level2]" in both places
• Fix: Ensure data exists for drill-down levels

NULL value errors

• Issue: Chart fails or shows incorrectly
• Fix: TreeMaps are sensitive to NULL values. Always exclude them:

  $olap.addGraph("1", "Title", "[level1]:[level2]", "[level1] IS NOT NULL AND [level2] IS NOT NULL","0");

Rectangles too small

• Issue: Many small rectangles hard to see
• Fix: Use limit to show only top N items:

  $olap.addGraphData("1","1","Revenue", "[item]", "sum([amount])", "treemap","","","20","M");

• Fix: Filter to relevant subset before charting

Wrong proportions

• Issue: Rectangle sizes don’t match expected values
• Check: Verify measure calculation (use sum, not avg for totals)
• Check: Ensure filter doesn’t exclude part of hierarchy
• Check: NULL values may affect calculations

Important

TreeMap graphs can only be built on the data source for the report. You cannot use setGraphSource to point to alternative data sources for treemaps.

FAQ

Q: Can I use setGraphSource with treemaps?
A: No, treemaps can only use the report’s main data source. Alternative sources are not supported.

Q: How many levels can I have?
A: Typically 2-4 levels work well. More levels can make the treemap cluttered and hard to navigate.

Q: What’s the difference between treemap and pie charts?
A: Treemaps show hierarchical data with drill-down. Pies show flat proportional breakdowns. Use treemap for multi-level data, pie for single-level.

Q: Can I sort the rectangles?
A: Yes, use orderby: "M" to sort by measure (largest first). This helps show most important items prominently.

Q: How do I limit which items appear?
A: Use the limit parameter in addGraphData to show only top N items, or filter in addGraph to focus on specific subset.

Q: Why do I get errors with NULL values?
A: TreeMaps are sensitive to NULLs. Always filter them out: "[column] IS NOT NULL" in your filter expression.

Q: Can I have multiple treemap series?
A: No, treemaps work with a single series. For multiple breakdowns, create separate graphs.

Q: How do I ensure drill-down works?
A: The hierarchy in addGraph split element must exactly match the hierarchy in addGraphData series. Both must use the same columns in the same order.

Related

• Graph Method Overview - Complete reference for all graph methods
• Pie - Alternative proportional visualization (single level)
• Column - Stacked columns as alternative
• addGraphData - Method documentation