TM 定义参考

本文面向需要编写或审查 Foggy Table Model（TM）的开发者，按定义对象和属性组织当前公开语义建模契约。本文只描述 TM 定义本身；QM 暴露字段和 DSL 查询语法请分别参考 QM 定义参考 和 JSON Query DSL 语法参考。

TM 描述物理数据如何进入 Foggy 语义层，包括物理表、字段、维度关系、指标、类型和公式。TM 字段不等于 DSL 可查询字段；字段需要进入当前 QM 的可见字段集合后，才可被查询调用方引用。预聚合属于查询引擎优化能力，本文只保留入口说明，详细能力见 预聚合能力参考。

1. TM 文件结构

TM 文件使用 JavaScript 模块语法，导出 model 对象。

export const model = {
    name: 'FactSalesModel',
    caption: '销售事实表',
    description: '销售订单明细数据',
    tableName: 'fact_sales',
    idColumn: 'sales_key',

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

1.1 model 顶层属性

¹ tableName 和 viewSql 通常二选一。

2. 维度定义

维度定义事实表与维度表之间的语义关系。引擎根据维度定义生成关联查询，LLM 不需要直接推断 JOIN 路径。

dimensions: [
    {
        name: 'customer',
        caption: '客户',
        tableName: 'dim_customer',
        foreignKey: 'customer_key',
        primaryKey: 'customer_key',
        captionColumn: 'customer_name',
        properties: [
            { column: 'customer_type', caption: '客户类型', type: 'STRING' },
            { column: 'province', caption: '省份', type: 'STRING' }
        ]
    }
]

2.1 dimension 属性

¹ tableName 和 viewSql 通常二选一。

2.2 captionDef

captionDef 用于定义 维度名$caption 的来源。它适合处理 JSON 翻译字段、跨方言表达式或不能直接用单列表达的显示值。

{
    name: 'product',
    tableName: 'product_template',
    foreignKey: 'product_id',
    primaryKey: 'id',
    captionDef: {
        column: 'name',
        dialectFormulaDef: {
            postgresql: {
                builder: (alias) => `${alias}.name ->> 'en_US'`
            }
        },
        formulaDef: {
            builder: (alias) => `${alias}.name`
        }
    }
}

优先级为：captionDef.dialectFormulaDef > captionDef.formulaDef > captionDef.column > 外层 captionColumn。

2.3 嵌套维度引用

嵌套维度使用 . 表示建模路径，使用 $ 表示属性访问。

响应列名中，嵌套维度路径里的 . 通常转为 _，例如 product.category$caption 对应 product_category$caption。面向 DSL 调用方时，应以当前 QM 暴露的最终字段名为准。

2.4 父子维度属性

父子维度用于组织架构、品类树等层级结构。

父子维度依赖闭包表表达祖先和后代关系。维度主表仍提供成员本身的 primaryKey、captionColumn 和普通属性；闭包表提供层级关系，供成员查询和 DSL 层级操作使用。

{
    name: 'team',
    caption: '团队',
    tableName: 'dim_team',
    foreignKey: 'team_id',
    primaryKey: 'id',
    captionColumn: 'name',
    closureTableName: 'dim_team_closure',
    parentKey: 'ancestor_id',
    childKey: 'descendant_id'
}

父子维度配合 DSL 的 childrenOf、descendantsOf、selfAndDescendantsOf 等操作符使用。是否允许这些层级操作，可以通过 memberPermission.patch.hierarchyEnabled 和 memberPermission.patch.allowedHierarchyOps 控制。

建模时需要确保闭包表中至少能表达直接父子和自包含关系；如果宿主系统只维护邻接表，需要先由同步任务或数据库作业生成闭包表。

2.5 维度成员权限

维度可声明 memberPermission，控制 synthetic member-QM 或成员查询时可见的成员字段、强制过滤、排序和层级操作范围。QM 可通过 memberPermissions[] 对指定维度做覆盖。

{
    name: 'product',
    tableName: 'dim_product',
    foreignKey: 'product_key',
    primaryKey: 'product_key',
    captionColumn: 'product_name',
    properties: [
        { column: 'brand', caption: '品牌' }
    ],
    memberPermission: {
        patch: {
            visibleColumns: ['id', 'caption', 'brand'],
            forcedSlice: [
                { field: 'enabled', op: '=', value: true }
            ],
            forcedOrderBy: [{ field: 'caption', dir: 'ASC' }],
            hierarchyEnabled: true,
            allowedHierarchyOps: ['childrenOf', 'descendantsOf']
        },
        queryBuilder: (context) => {
            context.query.and(context.member.enabled, true);
        }
    }
}

3. 属性定义

properties 描述非聚合字段，通常用于明细字段、枚举字段、状态字段、日期字段等。

properties: [
    {
        column: 'order_status',
        caption: '订单状态',
        description: '订单生命周期状态',
        type: 'STRING'
    }
]

4. 指标定义

measures 描述可聚合字段。aggregation 是默认聚合方式，查询时可以在 DSL 中覆盖。

measures: [
    {
        column: 'sales_amount',
        caption: '销售金额',
        type: 'MONEY',
        aggregation: 'sum'
    }
]

¹ count 类型指标可以不绑定具体 column。

4.1 聚合方式

5. 公式与 AI 元数据

5.1 formulaDef

formulaDef 用于在 TM 中为绑定到物理列的字段或指标提供 SQL 表达式。当前 Java 引擎仍要求 TM property/measure 声明 column；如果需要不依赖单个物理列的纯计算输出，应优先在 QM column item 中使用 formula。

{
    name: 'amountInWan',
    column: 'amount',
    caption: '金额（万元）',
    type: 'MONEY',
    formulaDef: {
        builder: (alias) => `${alias}.amount / 10000`,
        description: '金额单位换算'
    }
}

5.2 dialectFormulaDef

dialectFormulaDef 用于为不同数据库方言提供不同 SQL 构建逻辑。它可用于属性、指标和维度 captionDef，优先级高于通用 formulaDef。

{
    name: 'localizedName',
    column: 'name',
    caption: '本地化名称',
    type: 'STRING',
    dialectFormulaDef: {
        postgresql: {
            builder: (alias) => `${alias}.name ->> 'en_US'`
        },
        mysql: {
            builder: (alias) => `JSON_UNQUOTE(JSON_EXTRACT(${alias}.name, '$.en_US'))`
        }
    },
    formulaDef: {
        builder: (alias) => `${alias}.name`
    }
}

5.3 semanticScaleFactor

semanticScaleFactor 用于声明物理存储单位和语义查询单位之间的比例。例如 ERP 系统把金额以“分”存储，对外分析希望以“元”查询，可以在物理列字段上声明缩放因子。

{
    column: 'amount_cent',
    name: 'amount',
    caption: '金额',
    type: 'MONEY',
    aggregation: 'sum',
    semanticScaleFactor: 100,
    semanticUnit: 'yuan',
    semanticUnitLabel: '元'
}

该能力适用于直接绑定物理列的 property 或 measure。不要把 semanticScaleFactor 与 formulaDef / dialectFormulaDef 混用；复杂换算应使用公式字段显式建模。

5.4 ai

ai 用于补充面向 LLM 的字段说明。

6. 数据类型

VECTOR、mongo、预聚合等高级能力依赖具体引擎或扩展模块；公开语法中可以建模，但上线前应在目标运行时验证。预聚合的匹配、刷新和运行边界见 预聚合能力参考。

7. 命名规则

JDBC 字段名通常由 snake_case 自动转为 camelCase，例如 order_count 转为 orderCount。当 column 自动转换后的名称已经符合期望时，可以省略 name；只有在 _id、缩写列名或需要自定义语义名时再显式声明 name。