docs/docs/en/data-sources/collection-tree/index.md
Tree collections are suitable for data with parent-child relationships, such as organizational structures, product categories, regional hierarchies, department directories, and knowledge-base directories. A Tree collection uses the adjacency-list model to store parent-child relationships, and each record can point to its own parent node.
You can create Tree collections only from the main data source. External databases, REST API data sources, and External NocoBase data sources do not support creating Tree collections.
Tree collections are suitable for these business scenarios:
In the main data source, click Create collection and select Tree collection to create a Tree collection.
The creation settings for a Tree collection are mostly the same as those for a general collection.
| Setting | Description |
|---|---|
| Collection display name | The name displayed for the collection, such as Organization, Product categories, or Regional hierarchy. |
| Collection name | The collection identifier used internally by APIs, relation fields, permissions, and workflows. |
| Inherits | Select a parent collection to inherit. This setting is visible only when the main database is PostgreSQL. |
| Categories | Collection categories affect only organization in Data source management; they do not change the collection structure. |
| Description | A description of the collection. State which hierarchy data it stores, who maintains it, and which page filters use it. |
| Preset fields | Preset fields. Keep system fields and Tree collection built-in fields when creating a Tree collection. |
After a Tree collection is created, it usually includes the following built-in fields. parentId, parent, and children store the hierarchy.
| Field | Field name | Description |
|---|---|---|
| ID | id | The default primary key that uniquely identifies a record. |
| Created at | createdAt | Automatically records when the record was created. |
| Created by | createdBy | Automatically records the user who created the record. |
| Updated at | updatedAt | Automatically records when the record was last updated. |
| Updated by | updatedBy | Automatically records the user who last updated the record. |
| Parent ID | parentId | Stores the parent-node ID. It is usually empty for root nodes. |
| Parent | parent | A many-to-one relation field that points to a parent node in the current collection. |
| Children | children | A one-to-many relation field representing child nodes of the current node. |
| Space | space | Available after enabling the Multi-space plugin. It isolates data by space and does not appear when Multi-space is not enabled. |
:::warning Note
Avoid circular relationships in Tree collection data. For example, do not make B the parent of A and A the parent of B. Circular relationships cause incorrect tree displays and filter results.
:::
Like a general collection, a Tree collection needs a primary key. Tree relation fields use the parent-node ID to relate to the primary-key record in the same collection.
If a Tree collection has no primary key, set Record unique key when editing the collection. Otherwise, blocks might not view or edit records correctly, and tree displays might not locate nodes reliably.
A Tree collection can use most of the data blocks for a general collection to create, read, update, and delete records. It can also work with tree-specific features:
| Block | Use |
|---|---|
| Table block | Displays hierarchical records for viewing and maintaining parent-child structures. |
| Form block | Creates or edits one Tree node record. |
| Details block | Views details of one Tree node. |
| Tree Filter block | Filters other data blocks with a tree structure. It is commonly used for category, organization, regional, and other hierarchical filters. |
In the collection list, click Edit next to a Tree collection to change its display name, category, description, simple pagination mode, Record unique key, and other settings.
Do not delete Tree collection parent-child relation fields or repurpose them casually. To adjust the hierarchy, update parent-node relations in the record data first.
In the collection list, click Delete next to a Tree collection to delete it.
Deleting a Tree collection deletes its collection metadata, actual database table, and hierarchy data. Before deleting it, confirm whether page blocks, Tree Filter blocks, relation fields, permissions, workflows, or APIs still depend on it.
:::danger Warning
Tree collections are often used as filter conditions for other blocks. After deleting a Tree collection, related Tree Filter blocks and page configurations that depend on its category hierarchy might stop working.
:::