预聚合能力参考

本文说明 Foggy Java 引擎中的预聚合能力。该能力已有模型定义、匹配、SQL 改写和测试覆盖，但在具体项目中是否启用，应结合真实数据规模、刷新链路、查询口径和性能收益做项目级验证。预聚合是查询性能优化能力，不改变 TM/QM 的字段语义，也不是 MCP 工具协议的一部分。

1. 能力定位

preAggregations 用于在 TM 上声明已经存在或可被刷新任务生成的预计算聚合表。查询执行时，引擎会根据当前查询的维度、时间粒度、指标、过滤条件和运行时配置，判断是否可以把原始聚合查询改写到预聚合表上执行。

在完成项目级验证后，它适合以下场景：

• 高频聚合分析，例如按天、按月、按客户、按商品分类汇总。
• 大事实表上的常用指标查询。
• 可以接受预计算刷新周期的数据看板或 AI 分析入口。
• 查询结果需要保留原有 QM 字段语义，但希望降低原始表扫描成本。

它不适合替代完整的语义建模，也不应默认对所有查询开启。字段是否可查询仍由 QM 决定；预聚合只决定一次查询能否走更快的物理执行路径。

2. 使用状态口径

公开文档中应按以下口径理解预聚合：

因此，预聚合在当前文档中定位为“高级可选优化能力”，而不是默认查询路径或核心语义层契约。

3. 与 TM/QM/DSL 的关系

调用方不需要在 DSL 中显式指定预聚合表。是否命中预聚合由引擎根据模型定义和运行时配置决定。

4. 基本定义

preAggregations: [
    {
        name: 'dailyProductSales',
        caption: '每日商品销售预聚合',
        tableName: 'preagg_daily_product_sales',
        priority: 80,
        dimensions: ['salesDate', 'product'],
        granularity: {
            salesDate: 'day'
        },
        dimensionProperties: {
            product: ['caption', 'categoryName', 'brand']
        },
        measures: [
            { name: 'salesAmount', aggregation: 'sum', columnName: 'sales_amount' },
            { name: 'quantity', aggregation: 'sum', columnName: 'quantity' },
            { name: 'orderCount', aggregation: 'count', columnName: 'order_count' }
        ],
        refresh: {
            strategy: 'INCREMENTAL',
            watermarkColumn: 'salesDate$id',
            lookbackDays: 1
        },
        enabled: true
    }
]

4.1 顶层属性

4.2 指标属性

当前匹配逻辑主要覆盖 sum、count、min、max 等可安全 rollup 的聚合。avg 需要 sum + count 才能稳定上卷，当前不应作为预聚合 rollup 的默认假设。

4.3 刷新属性

刷新元数据本身不会让表自动存在。实际项目需要由工程侧创建预聚合表，并通过刷新任务、调度服务或外部数据作业维护其中的数据。

5. 匹配规则

预聚合命中需要同时满足以下条件：

当多张预聚合表都可满足查询时，引擎会结合 priority、维度覆盖差异和粒度差异选择更合适的表。

6. 执行模式

hybrid 查询依赖水位字段和运行时配置，默认不应假定开启。开启后仍需要验证水位线、刷新周期和源表补偿区间是否符合业务口径。

7. 查询证据

命中预聚合后，执行上下文会记录预聚合使用情况。宿主系统可以在查询证据或调试信息中暴露这些字段：

这些字段用于解释查询计划和排查性能问题，不应被当作业务结果正确性的唯一证明。重要分析仍应结合源记录、SQL/DSL 证据和业务口径复核。

8. 刷新与维护

Foggy Java 项目中存在独立的预聚合 add-on，用于生成预聚合表 DDL、全量刷新 SQL、增量刷新 SQL，并提供刷新服务、调度和管理接口。该能力通常由宿主系统按部署环境接入。

项目中可以按两类方式维护预聚合表：

• 外部数据作业维护：由数仓、ETL、定时 SQL 或业务系统自行生成预聚合表。
• Foggy 预聚合 add-on 维护：由 add-on 根据模型定义生成刷新 SQL 并执行全量或增量刷新。

复杂维度属性、跨表属性、特殊方言 SQL 和事务边界需要在目标运行时验证。预聚合刷新链路属于工程集成能力，不应只依赖模型文件声明。

9. 当前边界

• 明细查询通常不会命中预聚合。
• 只有指标、没有分组维度的查询一般不作为主查询命中预聚合；returnTotal 聚合路径可能单独使用预聚合。
• 跨 TM 或复杂 JOIN 查询的预聚合匹配较保守，通常要求查询字段能由同一预聚合表覆盖。
• 自定义 SQL 条件会使预聚合匹配失败。
• avg 类指标不应默认依赖预聚合上卷。
• filters 字段可作为预聚合元数据声明，但生产使用前应验证内置过滤条件与查询过滤条件的兼容性。
• 预聚合表的数据新鲜度由刷新机制和水位线维护，不由 DSL 查询本身保证。
• 如果目标项目尚未实践预聚合，应先作为性能优化候选项验证，不应写入必须依赖预聚合的业务流程。

10. 建模建议

• 先根据真实高频查询选择预聚合维度，不要为所有维度组合建表。
• 时间维度优先从细粒度开始评估，例如日粒度可以服务月、季度等上卷分析。
• 只放入常用且可稳定聚合的指标。
• 维度属性只放入查询、过滤或展示中确实需要的字段。
• 为常用预聚合设置更高 priority，但仍应通过查询证据验证实际命中情况。
• 在上线前分别验证命中查询和未命中查询，确保未命中时能回退到原始查询路径。