父子维度

父子维度（Parent-Child Dimension）用于处理层级结构数据，如组织架构、商品分类、地区等。

1. 什么是父子维度

父子维度是一种自引用的层级结构，每个成员可以有一个父成员和多个子成员。

典型应用场景：

• 组织架构：公司 → 部门 → 团队 → 小组
• 商品分类：大类 → 中类 → 小类
• 地理区域：国家 → 省份 → 城市 → 区县
• 菜单权限：系统 → 模块 → 页面 → 功能

2. 闭包表模式

Foggy Dataset Model 使用闭包表（Closure Table）存储层级关系，预存所有祖先-后代关系，实现高效查询。

优势：

• 查询任意层级的祖先/后代只需一次简单查询
• 无需递归查询，性能更好
• 支持任意深度的层级结构

3. 数据表结构

3.1 维度表

存储维度成员的基本信息：

CREATE TABLE dim_team (
    team_id VARCHAR(64) PRIMARY KEY,
    team_name VARCHAR(100) NOT NULL,
    parent_id VARCHAR(64),
    level INT,
    status VARCHAR(20) DEFAULT 'ACTIVE'
);

3.2 闭包表

存储所有祖先-后代关系：

CREATE TABLE team_closure (
    parent_id VARCHAR(64) NOT NULL,  -- 祖先 ID
    team_id VARCHAR(64) NOT NULL,    -- 后代 ID
    distance INT DEFAULT 0,          -- 距离（0 表示自身）
    PRIMARY KEY (parent_id, team_id)
);

-- 建议索引
CREATE INDEX idx_team_closure_parent ON team_closure (parent_id);
CREATE INDEX idx_team_closure_child ON team_closure (team_id);

3.3 示例数据

以下示例数据来自 foggy-dataset-demo 项目，用于演示和测试。

组织架构

总公司 (T001)
├── 技术部 (T002)
│   ├── 研发组 (T003)
│   │   ├── 前端小组 (T006)
│   │   └── 后端小组 (T007)
│   └── 测试组 (T004)
└── 销售部 (T005)
    ├── 华东区 (T008)
    └── 华北区 (T009)

团队维度表 (dim_team)

闭包表 (team_closure)

共 25 条记录：9 条自身记录 + 16 条祖先-后代关系

销售事实表 (fact_team_sales)

共 18 条记录：9 个团队 × 2 天

汇总数据参考

4. TM 模型配置

export const model = {
    name: 'FactTeamSalesModel',
    caption: '团队销售事实表',
    tableName: 'fact_team_sales',
    idColumn: 'sales_id',

    dimensions: [
        {
            name: 'team',
            tableName: 'dim_team',
            foreignKey: 'team_id',
            primaryKey: 'team_id',
            captionColumn: 'team_name',
            caption: '团队',

            // === 父子维度配置 ===
            closureTableName: 'team_closure',  // 闭包表名（必填）
            parentKey: 'parent_id',            // 闭包表祖先列（必填）
            childKey: 'team_id',               // 闭包表后代列（必填）

            properties: [
                { column: 'team_id', caption: '团队ID' },
                { column: 'team_name', caption: '团队名称' },
                { column: 'parent_id', caption: '上级团队' },
                { column: 'level', caption: '层级', alias: 'teamLevel' }
            ]
        }
    ],

    properties: [...],
    measures: [...]
};

4.1 配置字段

5. 两种访问视角

父子维度提供两种访问视角，语义清晰，行为一致：

设计原则：

• 默认 = 普通维度：行为与非父子维完全一致，无"魔法"
• 层级 = 显式请求：用户明确使用 $hierarchy$ 才启用闭包表

5.1 默认视角（普通维度行为）

使用 team$id、team$caption 等列，行为与普通维度完全相同。

示例：只查 T001 自身的销售数据

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "=", "value": "T001" }
        ]
    }
}

生成的 SQL：

SELECT d1.team_name, t0.sales_amount
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
WHERE d1.team_id = 'T001'
GROUP BY d1.team_name

返回数据（只包含 T001 自身的销售）：

5.2 层级视角（使用闭包表）

使用 team$hierarchy$id、team$hierarchy$caption 等列，启用闭包表进行层级操作。

场景 1：层级汇总（汇总到祖先节点）

{
    "param": {
        "columns": ["team$hierarchy$caption", "salesAmount"],
        "slice": [
            { "field": "team$hierarchy$id", "op": "=", "value": "T001" }
        ],
        "groupBy": [
            { "field": "team$hierarchy$caption" }
        ]
    }
}

生成的 SQL：

SELECT d4.team_name AS "team$hierarchy$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
LEFT JOIN dim_team d4 ON d2.parent_id = d4.team_id
WHERE d2.parent_id = 'T001'
GROUP BY d4.team_name

返回数据：

说明：T001 及其所有后代（T002-T009）的销售数据汇总显示为"总公司"。

场景 2：后代明细（分别显示各后代）

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$hierarchy$id", "op": "=", "value": "T001" }
        ],
        "groupBy": [
            { "field": "team$caption" }
        ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T001'
GROUP BY d1.team_name

返回数据（9 条记录，每个后代一条）：

说明：使用 team$hierarchy$id 过滤后代范围，但用默认的 team$caption 分组显示各团队明细。

5.3 视角对比总结

假设 T001（总公司）有 9 个团队（包括自身），各团队都有销售数据：

5.4 层级操作符

除了 $hierarchy$ 视角，还支持通过 op 操作符进行细粒度层级查询，无需使用 $hierarchy$ 列名：

所有操作符均支持 maxDepth 参数限制查询深度。

5.4.1 childrenOf - 查询直接子节点

查询指定节点的直接子节点（distance = 1）。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "childrenOf", "value": "T001" }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T001' AND d2.distance = 1
GROUP BY d1.team_name

返回数据（T001 的直接子部门）：

5.4.2 descendantsOf - 查询所有后代

查询指定节点的所有后代，不包含自身（distance > 0）。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "descendantsOf", "value": "T001" }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T001' AND d2.distance > 0
GROUP BY d1.team_name

返回数据（T001 的所有后代，不含 T001）：

5.4.3 selfAndDescendantsOf - 查询自身及所有后代

查询指定节点及其所有后代（等效于 $hierarchy$ 视角）。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "selfAndDescendantsOf", "value": "T001" }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T001'
GROUP BY d1.team_name

返回数据（T001 及所有后代）：

5.4.4 selfAndAncestorsOf - 查询自身及所有祖先

查询指定节点及其所有祖先（反向 JOIN 闭包表）。典型场景：Odoo parent_of 权限规则。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "selfAndAncestorsOf", "value": "T003" }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL（注意 JOIN 方向反转）：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.parent_id
WHERE d2.team_id = 'T003'
GROUP BY d1.team_name

返回数据（T003 研发组 + 其所有祖先）：

5.4.5 ancestorsOf - 查询所有祖先（不含自身）

查询指定节点的所有祖先，不包含自身（distance > 0）。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "ancestorsOf", "value": "T003" }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.parent_id
WHERE d2.team_id = 'T003' AND d2.distance > 0
GROUP BY d1.team_name

返回数据（T003 的祖先，不含 T003 自身）：

5.4.6 maxDepth - 限制查询深度

使用 maxDepth 参数限制层级查询的深度。

示例 1：查询 T001 的 2 级以内后代

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "descendantsOf", "value": "T001", "maxDepth": 2 }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T001' AND d2.distance BETWEEN 1 AND 2
GROUP BY d1.team_name

返回数据（T001 的 2 级以内后代，即子和孙）：

注：不包含 T006（前端小组）和 T007（后端小组），因为它们距离 T001 是 3 级。

示例 2：childrenOf + maxDepth（扩展子节点范围）

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "childrenOf", "value": "T002", "maxDepth": 2 }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id = 'T002' AND d2.distance BETWEEN 1 AND 2
GROUP BY d1.team_name

返回数据（T002 的 2 级以内子节点）：

5.4.7 多值查询

层级操作符支持传入多个值，查询多个节点的后代。

请求：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            { "field": "team$id", "op": "childrenOf", "value": ["T002", "T005"] }
        ],
       "groupBy": [
          { "field": "team$caption" }
       ]
    }
}

生成的 SQL：

SELECT d1.team_name AS "team$caption",
       SUM(t0.sales_amount) AS "salesAmount"
FROM fact_team_sales t0
LEFT JOIN dim_team d1 ON t0.team_id = d1.team_id
LEFT JOIN team_closure d2 ON t0.team_id = d2.team_id
WHERE d2.parent_id IN ('T002', 'T005') AND d2.distance = 1
GROUP BY d1.team_name

返回数据（T002 和 T005 的直接子节点）：

5.4.8 操作符对比表

6. 闭包表维护

6.1 新增节点

-- 添加新团队 T010（隶属于研发组 T003）
INSERT INTO dim_team VALUES ('T010', '后端小组', 'T003', 4, 'ACTIVE');

-- 插入自身关系
INSERT INTO team_closure (parent_id, team_id, distance)
VALUES ('T010', 'T010', 0);

-- 插入所有祖先到新节点的关系
INSERT INTO team_closure (parent_id, team_id, distance)
SELECT parent_id, 'T010', distance + 1
FROM team_closure
WHERE team_id = 'T003';

6.2 删除节点

DELETE FROM team_closure WHERE team_id = 'T010' OR parent_id = 'T010';
DELETE FROM dim_team WHERE team_id = 'T010';

7. 与普通维度的区别

8. 最佳实践

1. 索引优化：在闭包表的 parent_id 和 team_id 列建立索引
2. 数据一致性：使用事务确保维度表和闭包表的一致性
3. 层级深度：建议控制层级深度，过深会影响性能
4. distance 字段：虽非必需，但有助于查询特定层级的数据
5. 视角选择：
   • 精确匹配某节点 → 使用默认视角 team$id
   • 需要汇总到某节点 → 使用 team$hierarchy$id + team$hierarchy$caption
   • 需要查看后代明细 → 使用 team$hierarchy$id + team$caption

下一步

• JSON 查询 DSL - 查询 DSL 完整语法（推荐阅读）
• TM 语法手册 - 完整的 TM 定义语法
• QM 语法手册 - 查询模型定义
• 查询 API - HTTP API 接口