Create a hierarchical tree table
This guide shows you how to create a hierarchical tree table from a table whose rows reference each other through an ID column and a parent column.
If your rows don't reference each other and you instead want to group rows by column values and aggregate each group, use a rollup table.
A tree table is a table with an expandable tree structure. The following diagram shows one:
In computer science, trees are data structures used to represent hierarchical relationships between pieces of data. A tree stores its data in nodes. Each box in the diagram above is a node.
Every node except the root (the Root box at the top of the diagram) has exactly one parent, and any node can have zero or more children. In the diagram above, B7's parent is A3, and its children are C1 and C2.
In a Deephaven tree table, the Root node at the top of the diagram is implicit and doesn't correspond to a row. Its children, like A1, A2, and A3, are the rows whose parent is null. These rows are the top-level nodes of the tree.
A row whose parent value isn't null but doesn't match any row's ID, like Orphan in the diagram, is an orphan. See Orphan nodes.
tree
Create a tree table with the tree method:
Where:
idColumnis the name of the column that contains the unique identifier for each node in the tree.parentColumnis the name of the column that contains the identifier of each node's parent. Rows with a null parent are top-level nodes.
A row is a child of the row whose ID matches the row's parent value. The ID and parent columns must have the same data type.
The source table can be static or ticking, but tree doesn't support blink tables. See Unsupported operations.
By default, the tree leaves out orphans and their descendants. To keep them, see Orphan nodes.
The resulting table initially shows only the top-level rows, collapsed. Click a row to expand it and show its children.

tree returns a TreeTable, not a table, so you filter and sort it with its own methods. To filter it, use withFilter. To sort or filter the rows within each node, record the operations with makeNodeOperationsRecorder and apply them with withNodeOperations.
Examples
Static data
The following example creates a source table in which each row's Parent is its ID divided by 4, rounded down. The row with ID 0 has a null parent, so it is the only top-level node. The example then builds a tree from the ID and Parent columns.
Real-time data
Because Deephaven tables can tick, a tree table isn't a static copy of its source. When rows are added to, modified in, or removed from the source table, the tree updates to match, and you don't write any code to rebuild it. The following example builds a ticking tree from three tables:
t1has 10,000 rows with the same kind ofID/Parenthierarchy as the static data example. Each row'sParentis itsIDdivided by 10, rounded down.t2starts from a time table that adds a row every 10 milliseconds. ItsIcolumn counts from 0 to 9,999 and then wraps back to 0.lastBykeeps only the latest row for eachI, sot2never has more than 10,000 rows.sourcejoinst1tot2, so it contains only the rows whoseIDmatches anIvalue int2.
The tree grows as rows arrive. After I wraps back to 0, the tree updates in place instead of growing.

Orphan nodes
A row in a tree table is an orphan if both of the following are true:
- The row's parent is not null.
- No row in the table has that parent's ID.
By default, orphans and all of their descendants don't appear in the tree table. To include them, use the static promoteOrphans method of the TreeTable interface:
- Pass the source table, the ID column name, and the parent column name to
promoteOrphans. It returns a table in which each orphan's parent is null. - Call
treeon that table.
The promoted orphans become top-level nodes alongside the rows whose parent is null, and their descendants appear beneath them.
In the following example, source merges a 100-row table with a 2-row table. In source:
IDvalues run from 2 to 103.- The rows with
ID2, 102, and 103 have a null parent. - Every other row's parent is a number from 0 to 8. No row has an
IDof 0 or 1, so the rows whose parent is 0 or 1 are orphans. - Some orphans have descendants of their own. The row with
ID3 is an orphan, and the rows withID5, 7, and 9 are among its descendants.
resultNoOrphans leaves out the orphans and their descendants. resultWithOrphans shows the orphans as top-level nodes with their descendants beneath them.
The following figure shows the end of source next to resultNoOrphans. The rows with ID 2, 102, and 103 are top-level nodes. Orphans such as the rows with ID 92, 93, and 101, whose parents are 0 or 1, don't appear in the tree.

resultWithOrphans has more top-level nodes. Besides the rows with ID 2, 102, and 103, the promoted orphans are now top-level, including the rows with ID 3, 11, and 12. Expand the row with ID 3 to see its child, the row with ID 5.
Related documentation
- Table types
- Create a hierarchical rollup table
- Multi-aggregation
- Create static tables
- How to create a time table
- Exact and relational joins
- Inexact, time-series, and range joins
- Merge tables
emptyTablejoinlastBymergetimeTabletreeupdateViewTable.treeJavadocTreeTableJavadocTreeTable.withFilterJavadocTreeTable.makeNodeOperationsRecorderJavadocTreeTable.withNodeOperationsJavadoc