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:

A tree diagram: an implicit root above the top-level nodes A1, A2, and A3, their descendants down to C1 and C2, and a separate orphan node whose parent ID matches no row

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:

  • idColumn is the name of the column that contains the unique identifier for each node in the tree.
  • parentColumn is 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.

A user expands nodes in a tree table

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:

  • t1 has 10,000 rows with the same kind of ID/Parent hierarchy as the static data example. Each row's Parent is its ID divided by 10, rounded down.
  • t2 starts from a time table that adds a row every 10 milliseconds. Its I column counts from 0 to 9,999 and then wraps back to 0. lastBy keeps only the latest row for each I, so t2 never has more than 10,000 rows.
  • source joins t1 to t2, so it contains only the rows whose ID matches an I value in t2.

The tree grows as rows arrive. After I wraps back to 0, the tree updates in place instead of growing.

Animated GIF showing how a tree table updates in real time as data changes

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:

  1. 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.
  2. Call tree on 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:

  • ID values run from 2 to 103.
  • The rows with ID 2, 102, and 103 have a null parent.
  • Every other row's parent is a number from 0 to 8. No row has an ID of 0 or 1, so the rows whose parent is 0 or 1 are orphans.
  • Some orphans have descendants of their own. The row with ID 3 is an orphan, and the rows with ID 5, 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.

The source table next to a tree table. The rows with ID 2, 102, and 103 are top-level nodes, and the orphan rows with ID 92, 93, and 101 are absent

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.