Hierarchical Data

The hierarchy property in a table schema enables hierarchical (tree-structured) data modeling within a single table.

When hierarchy is configured:

• Records are organized into parent–child relationships.

• The table is interpreted as a tree instead of a flat list.

• The hierarchical structure is derived from record data.

• Stored data is not duplicated or transformed.

Hierarchy is a schema-level structural configuration.

It does not introduce cross-table relationships.

Basic Structure

Hierarchy is defined in the table schema:

interface ISchemaOption {
    hierarchy?: IHierarchyOption;
}

interface IHierarchyOption {
    type: 'Parent' | 'ChildrenPath' | 'Level' | 'Custom';
    column: string;
    outlineColumn?: string | IHierarchyOutlineColumnOptions;
    summaryFields?: { [field: string]: string };
    parse?: (options) => any;
    unparse?: (options) => any;
}

The configuration specifies how parent–child relationships are derived from record fields.

Supported Hierarchy Types

Hierarchy behavior depends on the type property.

Parent Type

Records contain both:

• A primary key field

• A parent reference field

Example data:

[
  { id: 1, parentId: -1 },
  { id: 2, parentId: -1 },
  { id: 3, parentId: 1 }
]

Configuration:

schema: {
    hierarchy: {
        type: "Parent",
        column: "parentId"
    },
    columns: {
        id: { isPrimaryKey: true },
        parentId: {}
    }
}

The column identifies the field that references the parent record.

The primary key is required to uniquely identify nodes.

Level Type

Hierarchy is determined by:

• A level indicator field

• The order of records

Example:

[
  { name: "USA", level: -1 },
  { name: "Texas", level: 0 },
  { name: "Houston", level: 1 }
]

Configuration:

hierarchy: {
    type: "Level",
    column: "level"
}

The level value determines the depth of each record relative to its neighbors.

A primary key is optional but recommended.

ChildrenPath Type

Records contain nested child collections.

Example:

[
  {
    name: "USA",
    children: [
      { name: "Texas" }
    ]
  }
]

Configuration:

hierarchy: {
    type: "ChildrenPath",
    column: "children"
}

The column specifies the property that contains child records.

Custom Type

Hierarchy is derived from a custom parsing rule.

Example:

[
  { id: "1" },
  { id: "1.1" },
  { id: "1.1.1" }
]

Configuration:

hierarchy: {
    type: "Custom",
    column: "id",
    parse: function (options) {
        const segments = options.data.id.split(".");
        return segments.slice(0, -1).join(".");
    }
}

The parse function derives the parent key from each record.

An optional unparse function can define how new keys are generated.

Summary Fields

Hierarchy supports summary fields for parent records.

hierarchy: {
    type: "Parent",
    column: "parentId",
    summaryFields: {
        budget: '=SUM(CHILDREN(1,"budget"))'
    }
}

Summary fields:

• Apply formulas to parent records

• Are evaluated only when a record has children

• Override editable behavior for summarized fields

These formulas are evaluated during calculation and do not alter stored child values.

Outline Column

An outline column defines which column visually represents the tree structure when rendered in a compatible view.

It can be specified:

• In hierarchy.outlineColumn

• Or at column/view level

When both are defined:

• View-level configuration overrides schema-level settings.

Hierarchy configuration itself does not render UI.

It only provides structural metadata.

Structural Constraints

Hierarchy modeling may require:

• A primary key (for Parent and often Custom types)

• A numeric rowOrder column for stable reordering (if supported by consuming views)

Hierarchy does not:

• Create cross-table relationships

• Modify remote synchronization semantics

• Duplicate records

It restructures how records are interpreted inside the table.

Responsibility Boundary

Hierarchy is a schema-level data structure configuration.

It:

• Defines parent–child relationships within a single table

• Influences calculation context and structural interpretation

• Is consumed by views that support hierarchical rendering

View-specific operations (such as expand, collapse, or reordering) are documented separately.

This separation ensures that data structure and UI behavior remain decoupled.