Skip to main content
Version: Python

Create a hierarchical tree table

This guide will show you how to create a hierarchical tree table. A tree table is a table with an expandable tree structure, as seen in the diagram below:

img

In computer science, trees are data structures used to represent hierarchical relationships between pieces of data. The data within the tree is stored in nodes, which are represented by the boxes in the diagram above.

Every tree table has one (and only one) root node, which is the topmost node in the tree. Aside from the root node, all other nodes in the tree follow the same rules: each node can have one (and only one) parent, and zero or more children. In the diagram above, B7's parent is A3, and its children are C1 and C2. Nodes with no children are known as leaf nodes, or leaves, as they are the terminal nodes of the tree structure. B3 and C1 are both leaves in the diagram above.

A node with no parent is known as an orphan, and will appear in the table outside of the tree structure.

tree​

In Deephaven, tree tables are created using the tree method. This method takes three arguments:

result = source.tree(id_col, parent_col, promote_orphans)

Where:

  • id_col is the name of the column that contains the unique identifier for each node in the tree.
  • parent_col is the name of the column that contains the unique identifier for the parent of each node in the tree.
  • promote_orphans is an optional boolean that determines whether nodes with no parent should be promoted to be children of the root node rather than appearing outside of the tree structure. By default, this is set to False.

The resulting table is initially collapsed, only showing the root node. Clicking on that node will expand it to show its children, and so on. Rows in the initial table with a parent_col value equal to a row in the id_col column will appear as children of the parent row.

img

Examples​

Static data​

The first example creates two constituent tables, which are then joined together to form the source table. The ID and Parent columns in source are used as the ID and parent columns, respectively.

from deephaven.constants import NULL_INT
from deephaven import empty_table

source = empty_table(100).update_view(
    ["ID = i", "Parent = i == 0 ? NULL_INT : (int)(i / 4)"]
)

result = source.tree(id_col="ID", parent_col="Parent")

Real-time data​

Tree tables work in real-time applications the same way as they do in static contexts. This can be shown via an example similar to the one above.

from deephaven import empty_table, time_table
from deephaven.constants import NULL_INT

t1 = empty_table(10_000).update_view(
    ["ID = i", "Parent = i == 0 ? NULL_INT : (int)(i / 10)"]
)
t2 = time_table("PT0.01S").update_view(["I = i % 10_000"]).last_by("I")

source = t1.join(t2, "ID = I")

result = source.tree(id_col="ID", parent_col="Parent")

img

Orphan nodes​

Rows (nodes) in a tree table are considered "orphans" if:

  • The node in question is not the root node.
  • The node's parent is not null.
  • The node's parent does not exist in the table.

Non-root nodes where the parent is null are not considered orphans. They can appear in the tree table, but they will appear outside of the tree structure and will be unaffected by the promote_orphans argument. For example, see rows 102 and 103 in the following figure:

img

Note that these rows appear on the same level as the root node, outside of the tree structure.

Orphan nodes appear outside of the tree table's tree structure by default. In order to include orphans in a tree table as children of the root node, the optional argument promote_orphans can be switched to True.

The following example shows how the resulting tree table changes if orphans are promoted.

from deephaven.constants import NULL_INT
from deephaven import empty_table

source = empty_table(100).update_view(
    ["ID = i + 2", "Parent = i == 0 ? NULL_INT : i % 9"]
)

result_no_orphans = source.tree(id_col="ID", parent_col="Parent")
result_w_orphans = source.tree(id_col="ID", parent_col="Parent", promote_orphans=True)