Tree Entities

TypeORM supports the Adjacency list and Closure table patterns for storing tree structures. To learn more about hierarchy table take a look at this awesome presentation by Bill Karwin.
​Adjacency list​
​Nested set​
​Materialized Path (aka Path Enumeration)​
​Closure table​
​Working with tree entities​
Adjacency list
Adjacency list is a simple model with self-referencing. The benefit of this approach is simplicity, drawback is that you can't load big trees in all at once because of join limitations. To learn more about the benefits and use of Adjacency Lists look at this article by Matthew Schinckel. Example:
1
import {Entity, Column, PrimaryGeneratedColumn, ManyToOne, OneToMany} from "typeorm";
2
​
3
@Entity()
4
export class Category {
5
​
6
    @PrimaryGeneratedColumn()
7
    id: number;
8
​
9
    @Column()
10
    name: string;
11
​
12
    @Column()
13
    description: string;
14
​
15
    @ManyToOne(type => Category, category => category.children)
16
    parent: Category;
17
​
18
    @OneToMany(type => Category, category => category.parent)
19
    children: Category[];
20
}
Copied!
Nested set
Nested set is another pattern of storing tree structures in the database. Its very efficient for reads, but bad for writes. You cannot have multiple roots in nested set. Example:
1
import {Entity, Tree, Column, PrimaryGeneratedColumn, TreeChildren, TreeParent, TreeLevelColumn} from "typeorm";
2
​
3
@Entity()
4
@Tree("nested-set")
5
export class Category {
6
​
7
    @PrimaryGeneratedColumn()
8
    id: number;
9
​
10
    @Column()
11
    name: string;
12
​
13
    @TreeChildren()
14
    children: Category[];
15
​
16
    @TreeParent()
17
    parent: Category;
18
}
Copied!
Materialized Path (aka Path Enumeration)
Materialized Path (also called Path Enumeration) is another pattern of storing tree structures in the database. Its simple and effective. Example:
1
import {Entity, Tree, Column, PrimaryGeneratedColumn, TreeChildren, TreeParent, TreeLevelColumn} from "typeorm";
2
​
3
@Entity()
4
@Tree("materialized-path")
5
export class Category {
6
​
7
    @PrimaryGeneratedColumn()
8
    id: number;
9
​
10
    @Column()
11
    name: string;
12
​
13
    @TreeChildren()
14
    children: Category[];
15
​
16
    @TreeParent()
17
    parent: Category;
18
}
Copied!
Closure table
Closure table stores relations between parent and child in a separate table in a special way. It's efficient in both reads and writes. Example:
1
import {Entity, Tree, Column, PrimaryGeneratedColumn, TreeChildren, TreeParent, TreeLevelColumn} from "typeorm";
2
​
3
@Entity()
4
@Tree("closure-table")
5
export class Category {
6
​
7
    @PrimaryGeneratedColumn()
8
    id: number;
9
​
10
    @Column()
11
    name: string;
12
​
13
    @TreeChildren()
14
    children: Category[];
15
​
16
    @TreeParent()
17
    parent: Category;
18
}
Copied!
You can specify closure table name and / or closure table columns names by setting optional parameter options into @Tree("closure-table", options). ancestorColumnName and descandantColumnName are callback functions, which receive primary column's metadata and return column's name.
1
@Tree("closure-table", {
2
    closureTableName: "category_closure",
3
    ancestorColumnName: (column) => "ancestor_" + column.propertyName,
4
    descendantColumnName: (column) => "descendant_" + column.propertyName,
5
})
Copied!
Working with tree entities
To bind tree entities to each other, it is required to set the parent in the child entity and then save them. for example:
1
const manager = getManager();
2
​
3
const a1 = new Category("a1");
4
a1.name = "a1";
5
await manager.save(a1);
6
​
7
const a11 = new Category();
8
a11.name = "a11";
9
a11.parent = a1;
10
await manager.save(a11);
11
​
12
const a12 = new Category();
13
a12.name = "a12";
14
a12.parent = a1;
15
await manager.save(a12);
16
​
17
const a111 = new Category();
18
a111.name = "a111";
19
a111.parent = a11;
20
await manager.save(a111);
21
​
22
const a112 = new Category();
23
a112.name = "a112";
24
a112.parent = a11;
25
await manager.save(a112);
Copied!
To load such a tree use TreeRepository:
1
const manager = getManager();
2
const trees = await manager.getTreeRepository(Category).findTrees();
Copied!
trees will be following:
1
[{
2
    "id": 1,
3
    "name": "a1",
4
    "children": [{
5
        "id": 2,
6
        "name": "a11",
7
        "children": [{
8
            "id": 4,
9
            "name": "a111"
10
        }, {
11
            "id": 5,
12
            "name": "a112"
13
        }]
14
    }, {
15
        "id": 3,
16
        "name": "a12"
17
    }]
18
}]
Copied!
There are other special methods to work with tree entities through TreeRepository:
findTrees - Returns all trees in the database with all their children, children of children, etc.
1
const treeCategories = await repository.findTrees();
2
// returns root categories with sub categories inside
3
​
4
const treeCategoriesWithLimitedDepth = await repository.findTrees({ depth: 2 });
5
// returns root categories with sub categories inside, up to depth 2
Copied!
findRoots - Roots are entities that have no ancestors. Finds them all. Does not load children leafs.
1
const rootCategories = await repository.findRoots();
2
// returns root categories without sub categories inside
Copied!
findDescendants - Gets all children (descendants) of the given entity. Returns them all in a flat array.
1
const children = await repository.findDescendants(parentCategory);
2
// returns all direct subcategories (without its nested categories) of a parentCategory
Copied!
findDescendantsTree - Gets all children (descendants) of the given entity. Returns them in a tree - nested into each other.
1
const childrenTree = await repository.findDescendantsTree(parentCategory);
2
// returns all direct subcategories (with its nested categories) of a parentCategory
3
const childrenTreeWithLimitedDepth = await repository.findDescendantsTree(parentCategory, { depth: 2 });
4
// returns all direct subcategories (with its nested categories) of a parentCategory, up to depth 2
Copied!
createDescendantsQueryBuilder - Creates a query builder used to get descendants of the entities in a tree.
1
const children = await repository
2
    .createDescendantsQueryBuilder("category", "categoryClosure", parentCategory)
3
    .andWhere("category.type = 'secondary'")
4
    .getMany();
Copied!
countDescendants - Gets number of descendants of the entity.
1
const childrenCount = await repository.countDescendants(parentCategory);
Copied!
findAncestors - Gets all parent (ancestors) of the given entity. Returns them all in a flat array.
1
const parents = await repository.findAncestors(childCategory);
2
// returns all direct childCategory's parent categories (without "parent of parents")
Copied!
findAncestorsTree - Gets all parent (ancestors) of the given entity. Returns them in a tree - nested into each other.
1
const parentsTree = await repository.findAncestorsTree(childCategory);
2
// returns all direct childCategory's parent categories (with "parent of parents")
Copied!
createAncestorsQueryBuilder - Creates a query builder used to get ancestors of the entities in a tree.
1
const parents = await repository
2
    .createAncestorsQueryBuilder("category", "categoryClosure", childCategory)
3
    .andWhere("category.type = 'secondary'")
4
    .getMany();
Copied!
countAncestors - Gets the number of ancestors of the entity.
1
const parentsCount = await repository.countAncestors(childCategory);
Copied!
For the following methods, options can be passed:
findTrees
findRoots
findDescendants
findDescendantsTree
findAncestors
findAncestorsTree
The following options are available:
relations - Indicates what relations of entity should be loaded (simplified left join form).
Examples:
1
const treeCategoriesWithRelations = await repository.findTrees({ relations: ["sites"] });
2
// automatically joins the sites relation
3
​
4
const parentsWithRelations = await repository.findAncestors(childCategory, { relations: ["members"] });
5
// returns all direct childCategory's parent categories (without "parent of parents") and joins the 'members' relation
Copied!

Transactions

Troubleshooting

Last modified 30d ago

Copy link

Contents

Adjacency list

Nested set

Materialized Path (aka Path Enumeration)

Closure table

Working with tree entities