第12章 湖仓引擎与 OLAP¶
湖仓引擎与 OLAP 是 Agent 分析链路中的执行层。DataAgent 生成的 SQL 最终要落到某个引擎上执行，选 Trino、ClickHouse 还是 StarRocks，直接影响延迟、并发和成本。多引擎路由、查询控制、安全边界和性能工程决定不同查询该走哪条执行路径，也决定平台能否用资源控制、超时和权限边界防止一条失控 SQL 拖垮系统。湖仓表已经保存好了数据，并不意味着查询链路已经可靠。一个经营分析 Agent 生成了跨三年订单明细的 Join 查询，默认路由到交互式引擎，结果占满资源池，财务看板和运营临时查询一起变慢。查询本身并非恶意，但它没有进入合适的执行队列，也没有被扫描量、超时和权限策略提前约束。OLAP 层要把自然语言生成的 SQL 变成受控执行。平台需要按工作负载、权限、预算和数据快照选择引擎，并把查询失败、慢查询和资源争抢反馈给 Agent，而非让模型直接把 SQL 扔给任意数据库。
OLAP 层是 DataAgent 从“会生成 SQL”走向“能稳定执行分析”的地方。用户不会关心查询跑在 Trino、ClickHouse 还是 StarRocks 上，但平台必须知道。一个跨年宽表 Join、一个明细级导出、一个秒级看板查询和一个离线归因任务，对引擎、队列、缓存和权限的要求完全不同。若所有 SQL 都丢给同一个入口，失控查询会占满资源，正常分析也会被拖慢。企业里常见的故障，是查询被放到了错误路径；数据库不可用只是一类情况。经营分析 Agent 为了回答一个追问，扫描了三年订单明细；临时分析占用了交互式资源池；用户以为系统卡住，反复重试，成本继续上升。模型生成的 SQL 语法正确，但执行层没有给它资源上限、超时、扫描量控制和队列隔离。湖仓和 OLAP 的设计要把 SQL 执行变成受控动作。Catalog 负责解释表在哪里，开放表格式负责维持快照和 schema，查询引擎负责执行，路由器负责把任务放到合适资源池。DataAgent 只负责提出分析意图和候选 SQL，最终执行要接受平台的权限、成本和性能约束。
12.1 OLAP 引擎在 DataAgent 分析执行链路中的角色¶
第11章 解决湖仓表如何可靠保存，第12章 解决这些表如何被查询、分析和服务。一家多业务线企业的数据已经通过采集链路进入湖仓，订单、库存、会员、工单和设备数据以开放表格式管理。但业务问题并不都适合同一个计算系统。财务看板要求稳定秒级返回，运营团队要高并发查询当天销售，数据科学家要在 Notebook 中读抽样文件，DataAgent 需要跨 MySQL、Iceberg 和指标层做探索。在线分析处理（Online Analytical Processing，OLAP）引擎的职责是面向大范围扫描、过滤、聚合、Join、排序和窗口函数做优化。它不同于在线事务处理（Online Transaction Processing，OLTP）数据库，后者服务短事务、点查、行级更新和高并发写入。Agent 平台若直接把复杂分析压到 OLTP 源库，会影响生产系统；若只把所有分析交给一个通用引擎，又会在延迟、成本或治理上付出代价。
OLAP 引擎可以理解为湖仓表和业务消费之间的“计算适配层”。湖仓保存数据资产，但用户需要的是指标、报表、探索结果和可解释 SQL 输出。不同消费方式对计算适配层的要求不同：看板要求稳定低延迟，临时分析要求灵活 SQL，事件分析要求高吞吐写入和时间过滤，本地探索要求低成本和易嵌入。若没有这层区分，平台会把所有查询塞进同一个系统，结果要么慢查询拖垮看板，要么为了低延迟报表牺牲探索灵活性。对 DataAgent 来说，OLAP 引擎还承担“可控执行”的职责。Agent 生成查询后，平台需要选择合适引擎、限制扫描量、应用权限策略、设置超时、记录审计并返回可解释错误。引擎不能被看作被动数据库，它是 Agent 分析链路中的执行边界。
图12-1：OLAP 引擎把湖仓数据变成可消费的数据服务。来源：本书自绘。Alt text：底层湖仓表经 OLAP 引擎查询后，向上提供给看板、API、DataAgent 等消费方，引擎位于"存储"与"消费"之间作为查询服务层。
图 12-1 展示了“同一份湖仓资产，多种消费方式”。DataAgent 的临时探索可以走 Trino，固定经营看板可以走 StarRocks 或 Doris，日志与事件分析可以走 ClickHouse，统一数据工程和机器学习可以走 Databricks，云数仓标准报表可以走 Snowflake，本地抽样验证可以走 DuckDB。重点不在于多装几个引擎，而在于用统一入口控制路由、权限、成本和审计。这里需要回答两个问题：哪类工作负载走哪条路径，以及这些路径是否仍被统一治理。
12.1.1 企业分析负载分类¶
引擎选型要从负载分类开始。产品名称本身不能说明问题，因为同一个 SQL 引擎在不同负载下表现可能完全不同。即席查询重视灵活连接和容错，固定仪表盘重视并发和稳定延迟，指标查询重视口径一致和可缓存，联邦查询重视连接器能力，本地探索重视单机效率和易用性，事件分析重视时间过滤和写入吞吐。先分清负载，平台才能给每类查询设置不同的延迟目标、预算、权限和降级策略。
表12-1：即席查询、报表、明细检索等分析负载的延迟目标与适配引擎。来源：本书整理。
| 负载 | 典型问题 | 延迟目标 | 更自然的引擎方向 |
|---|---|---|---|
| 即席查询 | “这个异常门店还能关联哪些供应商？” | 秒到分钟 | Trino、Databricks、Snowflake |
| 仪表盘 | “今日门店销售额按城市刷新” | 亚秒到数秒 | StarRocks、Doris、ClickHouse、Snowflake |
| 指标查询 | “同店同比、复购率、支付成功率” | 稳定秒级 | 物化视图、指标层、实时 OLAP |
| 联邦查询 | “湖仓订单 join MySQL 促销配置” | 秒到分钟 | Trino、Databricks federation |
| 本地探索 | “抽样 Parquet 验证口径” | 单机交互式 | DuckDB |
| 事件分析 | “最近 5 分钟点击流异常” | 秒级 | ClickHouse、StarRocks、Doris |
图12-2：企业分析负载决定引擎候选项。来源：本书自绘。Alt text：左侧列出即席查询、固定报表、明细点查、实时大屏等负载，箭头分别指向更合适的引擎类型，说明先看负载特征再定引擎。
图 12-2 表明，引擎选型应先识别负载类型。即席查询、仪表盘、指标查询、联邦查询、本地探索和事件分析对延迟、并发、成本和治理的要求不同，因此自然会落到不同的候选引擎组合。图中的候选项只是提示读者先把“查询为什么存在”讲清楚，再选择执行系统，并不是固定答案。
12.1.2 OLAP 核心机制¶
现代 OLAP 引擎通常围绕六类机制优化：列式存储只读必要列；编码和压缩减少 I/O；向量化执行批量处理数据；大规模并行处理（Massively Parallel Processing，MPP）把任务拆到多节点；优化器基于统计信息选择计划；缓存和物化视图减少重复计算。这些机制共同服务一个目标：用可接受的成本扫描大量数据并快速得到聚合结果。列式存储让查询只读 city 和 amount 这样的必要列，避免读取整行订单；压缩和编码减少磁盘与网络传输；向量化执行让 CPU 批量处理数据；MPP 把扫描和聚合拆到多个节点；优化器决定过滤和 Join 的顺序；缓存和物化视图减少重复计算。理解这些机制后，团队才能判断慢查询来自数据布局、统计信息、Join 计划，还是资源隔离。
图12-3：现代 OLAP 查询执行链路。来源：本书自绘。Alt text：横向链路依次为 SQL 解析、逻辑计划、优化器、分布式执行、结果返回，各阶段标注关键动作，体现一条查询从文本到结果的处理过程。
图 12-3 中容易被忽略的是优化器和数据布局。若没有统计信息，引擎可能选择错误 Join 顺序；若分区和排序键不匹配查询条件，再强的向量化执行也会变成大范围扫描。第11章的表格式、分区、文件大小和快照管理，会直接影响本章的查询成本。一次查询要先解析、优化、拆分、调度，再扫描和聚合；任何一步缺少输入信息，都会把成本放大到后续阶段。
12.1.3 OLAP 选型要先看工作负载¶
OLAP 引擎选型有三类常见偏差。第一类是认为有了湖仓表格式就不需要 OLAP 引擎。表格式解决数据资产开放性，查询性能仍取决于执行引擎、数据布局、统计信息、缓存和并发控制。表格式回答“读哪些文件才一致”，OLAP 引擎回答“如何高效读并计算这些文件”。第二类是把所有分析场景强行统一到一个引擎。统一能降低治理复杂度，也会牺牲特定负载的成本或延迟。更现实的做法是统一元数据、权限和审计，允许多个引擎围绕同一份数据协同。这里要统一的是控制平面，不是执行引擎本身。第三类是只看基准测试排行榜。基准测试不能替代对真实数据分布、真实 SQL、并发、写入模式、权限模型、成本和团队运维能力的评估。一个引擎在标准测试上很快，不代表它适合一家多业务线企业的权限模型、数据倾斜、冷热分层和 Agent 查询模式。
12.2 湖仓查询路径：Catalog、开放表格式、对象存储与计算引擎协作¶
一次受控湖仓查询通常经过五个步骤：用户或 DataAgent 提交查询意图；查询路由器选择引擎；策略控制器校验权限、预算和超时；Catalog 适配器解析表、快照和连接信息；执行适配器提交到具体引擎并返回结果句柄。这个路径的核心思想是“先控制，再执行”。DataAgent 生成的 SQL 只是查询意图的一种表达，还不能直接提交给底层引擎。平台必须先判断查询适合哪类负载，用户是否有权限，是否超过扫描预算，是否需要固定快照，是否应读取脱敏视图。只有这些判断完成后，执行适配器才把查询交给 Trino、StarRocks、Snowflake 或其他引擎。
图12-4：受控湖仓查询先过路由、策略和 Catalog。来源：本书自绘。Alt text：查询进入后依次经过查询路由器、策略引擎（权限/限额）、Catalog（元数据/行列权限），三道关卡通过后才提交引擎执行。
图 12-4 展示受控查询入口的基本路径。用户或 DataAgent 的查询意图先经过路由和策略校验，再通过 Catalog 解析表、快照和连接信息，然后提交给具体执行引擎。图中路由、策略和 Catalog 位于引擎之前，说明治理是执行前必须经过的控制点，而非查询完成后的审计补丁。
平台不建议让 DataAgent、BI 工具或业务系统直接裸连所有引擎。裸连会带来三个问题：权限口径不一致，成本无法归因，失败无法解释。统一接入层不一定是重型网关，也可以先从规则路由和审计记录开始。对早期平台来说，先记录工作负载标签、选择引擎、用户身份、快照和错误码，就已经能让排障和审计有据可查。
12.2.1 引擎生态对比¶
表12-2：平台型湖仓、MPP、实时 OLAP 等引擎类型的代表产品与适用场景。来源：本书整理。
| 类型 | 代表产品 | 为什么用 | 不适合什么场景 | 替代方案 |
|---|---|---|---|---|
| 平台型湖仓 | Databricks | 数据工程、SQL、机器学习和治理一体化 | 只服务单一低延迟看板时成本较高 | Snowflake、Doris/StarRocks + Spark |
| 云原生数仓 | Snowflake | SQL 数仓、弹性 warehouse、低运维 | 极低延迟事件分析或强本地化部署 | Databricks、ClickHouse、Doris |
| 实时 OLAP | Doris、StarRocks | 高并发报表、物化视图、MySQL 生态 | 任意跨源探索和重型数据工程 | Trino、Databricks、Snowflake |
| 事件分析 | ClickHouse | 日志、事件、时序和大宽表聚合 | 表设计不明确或频繁更新的强事务表 | StarRocks、Doris |
| 联邦查询 | Trino | 多源连接、开放湖仓入口 | 高频固定报表和高成本跨源 Join | 预建数据集、物化视图 |
| 嵌入式分析 | DuckDB | 本地文件、Notebook、轻量 ETL | 多租户、高并发、集群级治理 | Trino、Spark、本地服务化引擎 |
表 12-2 不是产品排名。Databricks 和 Snowflake 更像平台或托管服务，能覆盖较宽的治理和工程场景；Doris、StarRocks、ClickHouse 更偏向低延迟服务化分析；Trino 的价值在开放连接和联邦查询；DuckDB 的价值在本地与嵌入式。企业常见做法是先确定主路径，再给特殊负载保留合适工具，不必选一个赢家。
图12-5：七类湖仓与 OLAP 引擎的系统边界不同。来源：本书自绘。Alt text：七种引擎类型并排，各自标出存储耦合度、延迟特征、并发能力和适用负载，对比它们的系统边界差异。
图 12-5 的重点是系统边界。Databricks、Snowflake、Doris、StarRocks、ClickHouse、Trino 和 DuckDB 都能服务分析，但它们分别偏向平台化、托管数仓、实时服务、事件分析、联邦查询或本地探索。选型时要看每类引擎“负责到哪里”：有的包含治理和工程平台，有的主要负责执行，有的适合嵌入在本地进程中。
图 12-5 的含义是先确定系统边界，再比较产品能力。Databricks 和 Snowflake 偏平台化或托管体验；Doris、StarRocks、ClickHouse 偏低延迟服务化分析；Trino 偏连接器和联邦查询；DuckDB 偏单机本地分析。同一张 Iceberg 表可以被多个引擎读取，但每条访问路径都需要不同的 SLA、预算和运维 playbook。
12.2.2 SQL 方言、权限模型、资源组与多租户隔离¶
多引擎协同时，平台最容易低估的是非性能问题。SQL 方言差异会导致 DataAgent 生成的语句在一个引擎可运行、另一个引擎失败；权限模型差异会导致同一用户在不同入口看到不同列；资源组和 warehouse 配置差异会导致成本和并发不可控。路由器需要返回引擎名称，也要返回工作负载类型、SQL 方言、可访问表列、扫描预算，以及失败时能否换引擎。对 DataAgent 来说，方言差异尤其重要：同一个日期函数、JSON 函数或近似聚合函数，在不同引擎中的语法和语义可能不同。平台要么在生成 SQL 前绑定方言，要么在提交前做语法转换和校验。
表12-3：查询路由器、策略引擎等组件的职责、输入输出与失败模式。来源：本书整理。
| 组件 | 职责 | 输入 | 输出 | 失败模式 |
|---|---|---|---|---|
| 查询路由器 | 根据工作负载、数据位置、延迟和预算选择引擎 | 查询意图、SQL、用户、工作负载标签 | 引擎选择、查询提交请求 | 路由规则过期、误路由 |
| Catalog 适配器 | 映射平台资产到各引擎 catalog/schema/table | 元数据、权限、快照 | 引擎可识别的数据源定义 | 元数据漂移、凭证失效 |
| 策略控制器 | 执行权限、行列级策略、成本预算和并发限制 | 用户、角色、数据分级、预算 | 允许、拒绝或降级 | 权限漏放、预算失控 |
| 执行适配器 | 适配不同引擎协议 | 查询请求、连接信息、超时 | 查询状态、结果句柄 | 连接池耗尽、引擎不可用 |
| 可观测性采集器 | 记录耗时、扫描量、费用、错误和血缘 | 查询生命周期事件 | Trace、Metrics、审计日志 | 日志缺失、成本归因失败 |
接口契约示例：
POST /api/lakehouse/query
Request:
{
"principal": "user:finance_analyst_01",
"workload": "realtime_bi",
"sql": "select city, sum(amount) from mart.sales group by city",
"latency_budget_ms": 3000,
"cost_budget": "low",
"result_mode": "preview"
}
Response:
{
"query_id": "q_20260611_001",
"engine": "StarRocks",
"state": "submitted",
"result_ref": "lakehouse-results/q_20260611_001"
}
Errors:
{
"code": "POLICY_DENIED | ENGINE_UNAVAILABLE | QUERY_TIMEOUT | COST_BUDGET_EXCEEDED",
"reason": "...",
"retryable": true
}
这个接口契约把查询执行拆成可观测状态，而非简单返回一张结果表。workload 帮助路由器选择引擎，latency_budget_ms 和 cost_budget 帮助策略控制器做预算判断，result_mode 决定返回预览还是落地结果。错误码中的 retryable 也很关键：权限拒绝和预算超限通常不应自动重试，引擎暂时不可用才可能触发降级或换路由。
12.2.3 性能工程：物化视图、Rollup、数据分布、冷热分层与查询加速¶
性能工程要从查询模板和数据布局开始，而非先加机器。固定看板应优先使用物化视图、汇总表、Rollup 或服务化宽表；探索查询应限制扫描量和并发；日志事件分析应围绕排序键、分区和压缩设计；冷历史查询应接受更高延迟或走低成本引擎。性能工程的第一步，是把查询分成“重复发生”和“临时发生”。重复发生的查询，应尽量通过预计算、物化视图、缓存和宽表把成本前移；临时发生的查询，则要控制扫描范围和并发，避免少数探索请求拖垮共享集群。对 DataAgent 尤其如此，因为 Agent 可能在多轮对话中自动发起多个探索查询，如果没有预算和缓存，很容易把一次自然语言追问变成一组昂贵 SQL。
图12-6：性能工程把负载分流到预计算、缓存和探索路径。来源：本书自绘。Alt text：查询按特征分流，高频固定查询走物化视图/Rollup 预计算，重复查询走缓存，低频探索走联邦/直查，三条路径分别标注收益。
图 12-6 说明，性能工程先做负载分流，再谈扩容。高频看板走预计算和缓存，探索查询限制扫描量和并发，冷历史查询接受更高延迟或走低成本引擎。图中的分流逻辑与 12.2 的负载分类一一对应：先分类，再决定是否预计算、缓存、限流或降级。
单引擎统一与多引擎协同¶
表12-4：单引擎统一与多引擎路由两种架构的取舍。来源：本书整理。
| 方案 | 优势 | 代价 | 适用场景 | mini-platform 选择 |
|---|---|---|---|---|
| 单引擎统一 | 治理简单、运维集中、用户体验一致 | 特定负载性能或成本不优 | 组织早期、负载单一 | 可作为初始策略 |
| 多引擎协同 | 按负载选择成本和性能最优解 | 路由、权限、审计和一致性复杂 | 多团队、多负载、既有系统复杂 | 默认建模方式 |
联邦查询与预建数据集¶
表12-5：物化视图、联邦查询等查询加速手段的优势与代价。来源：本书整理。
| 方案 | 优势 | 代价 | 适用场景 | mini-platform 选择 |
|---|---|---|---|---|
| 联邦查询 | 快速跨源探索，不必先搬数 | 跨源 Join 成本和稳定性难预测 | 临时分析、低频探索、数据发现 | federated_query 路由到 Trino |
| 预建数据集 | 延迟稳定、成本可控、权限清晰 | 需要建模、调度和维护 | 高频报表、DataAgent 常用指标 | 生产路径优先 |
单引擎统一适合作为早期平台的过渡策略，但一旦负载分化，就需要至少在逻辑上区分执行路径。联邦查询也应被当作探索工具，而非长期报表路径；当某个联邦查询被频繁使用时，就应该沉淀成预建数据集、物化视图或指标层能力。这个转化过程，是数据平台从“能查”走向“稳定服务”的关键。
12.2.4 Agent 查询安全：只读执行、超时、限额、结果脱敏与审计¶
Agent 生成 SQL 后必须经过安全执行边界。最低要求包括只读执行、禁止危险语句、限制扫描量、设置超时、限制返回行数、脱敏敏感列、记录 SQL 摘要和结果去向。若查询失败，错误码需要能区分权限拒绝、预算超限、引擎不可用和 SQL 语义错误，避免 Agent 无意义重试。这里的安全需要同时防止删除表，也要防止“合法但危险”的查询。一个只读 SELECT 仍可能扫描全量历史、跨源 Join 巨表、返回过多敏感明细，或在用户没有授权的维度上聚合。Agent 的自动化能力越强，执行边界越要前置。平台应把 SQL 安全、数据权限、成本预算和结果脱敏作为同一条链路处理，避免拆成四个互相独立的开关。
图12-7：Agent 查询安全边界在引擎提交前生效。来源：本书自绘。Alt text：在 SQL 提交到引擎之前设置只读校验、超时、行数限额、结果脱敏四道关卡，箭头表示任一不通过即拦截，体现安全前置。
图 12-7 强调安全边界必须在查询提交前生效。只读执行、危险语句拦截、扫描量限制、超时、脱敏和审计应由平台统一执行，不能依赖 Agent 自觉生成安全 SQL。控制点都位于执行适配器之前，意味着不通过策略的查询根本不应到达底层引擎。状态机如下。
表12-6：Agent 查询从提交到完成各状态的进入条件与失败处理。来源：本书整理。
| 状态 | 进入条件 | 下一步 | 失败处理 |
|---|---|---|---|
| Submitted | 用户或 Agent 提交请求 | Planned 或 Rejected | 权限和预算不通过则拒绝 |
| Planned | 路由和策略通过 | Running 或 Failed | 引擎连接失败则返回可解释错误 |
| Running | 引擎接受查询 | Succeeded、TimedOut、Cancelled、Failed | 超时取消，避免无限重试 |
| Succeeded | 结果完成 | 审计并返回 result_ref | 大结果集分页或落对象存储 |
| TimedOut | 超过预算 | Retried 或 Failed | 改写查询、加过滤或换物化视图 |
| Cancelled | 用户或策略取消 | 终止 | 释放引擎资源并记录原因 |
图12-8：湖仓查询状态机支撑超时、取消和可解释失败。来源：本书自绘。Alt text：状态机含 Submitted、Planned、Running、Succeeded、Failed、Cancelled 等节点，标出超时和取消的转移边，说明每次失败都有明确状态可解释。
图 12-8 给出查询生命周期的状态边界。平台需要区分提交、规划、运行、成功、超时、取消和失败，才能正确决定是否重试、是否降级，以及向 Agent 返回什么可解释错误。状态机可以防止“失败就重试”的简单策略：权限拒绝应停止，超时应缩小范围或走物化视图，引擎不可用才考虑备用引擎。
12.3 湖仓引擎路由器与查询执行契约¶
mini-platform 不直接连接 Databricks、Snowflake、Doris、StarRocks、Trino、ClickHouse 或 DuckDB，而是先实现“负载到候选引擎”的规则模型。这样做的原因是：真实执行适配器之前，平台必须先定义工作负载分类、默认引擎、替代引擎、延迟预算和扫描预算。这个实现先定义路由规则，再接执行适配器。真实引擎连接会涉及账号、网络、驱动和部署环境；在这些工程细节之前，平台必须已经知道 realtime_bi 为什么默认走 StarRocks，federated_query 为什么默认走 Trino，local_analytics 为什么默认走 DuckDB。mini-platform 用规则模型先展示选型依据，避免一开始就陷入连接字符串和客户端参数。
- 入口：
mini-platform/infra/lakehouse/__init__.py - 核心实现：
mini-platform/infra/lakehouse/engine_selector.py - 测试：
mini-platform/tests/test_lakehouse_engine_selector.py - 实战项目：
mini-platform/projects/12-lakehouse-engine/run.py
图12-9：mini-platform 用工作负载标签生成引擎路由决策。来源：本书自绘。Alt text：查询带上工作负载标签（如 adhoc、report、realtime）进入路由器，路由器据标签和数据位置输出目标引擎，体现标签驱动路由。
图 12-9 对应本章 mini-platform 的路由流程：输入工作负载标签和延迟预算，规则模型返回主引擎、备选引擎、扫描预算和可行性判断。它展示的是查询控制面的最小版本，生产系统还需要接入权限、队列、缓存和审计。mini-platform/infra/lakehouse/engine_selector.py：
class Workload(str, Enum):
PLATFORM = "platform"
CLOUD_WAREHOUSE = "cloud_warehouse"
REALTIME_BI = "realtime_bi"
FEDERATED_QUERY = "federated_query"
EVENT_ANALYTICS = "event_analytics"
LOCAL_ANALYTICS = "local_analytics"
核心规则节选：
_RULES: dict[Workload, EngineChoice] = {
Workload.REALTIME_BI: EngineChoice(
primary="StarRocks",
alternatives=("Apache Doris", "ClickHouse"),
reason="高并发看板、低延迟聚合、物化视图和 MySQL 协议生态。",
latency_budget_ms=3000,
max_scan_gb=200,
),
Workload.FEDERATED_QUERY: EngineChoice(
primary="Trino",
alternatives=("Apache Doris", "Databricks Lakehouse Federation"),
reason="以连接器访问多源数据，适合作为开放湖仓 SQL 入口。",
latency_budget_ms=30000,
max_scan_gb=1024,
),
}
route_query 在 choose_engine 之上叠加调用方延迟预算：
def route_query(request: dict) -> dict:
choice = choose_engine(request["workload"])
requested = request.get("latency_budget_ms")
effective_budget = choice.latency_budget_ms
latency_feasible = True
if requested is not None:
effective_budget = min(effective_budget, requested)
latency_feasible = requested >= choice.latency_budget_ms
return {
"engine": choice.primary,
"alternatives": choice.alternatives,
"latency_budget_ms": effective_budget,
"max_scan_gb": choice.max_scan_gb,
"latency_feasible": latency_feasible,
"reason": choice.reason,
}
运行测试：
cd enterprise_agent_platform_book/mini-platform
python3 -m pytest tests/test_lakehouse_engine_selector.py -q
运行项目：
cd enterprise_agent_platform_book/mini-platform/projects/12-lakehouse-engine
PYTHONPATH=../.. python3 run.py
预期输出：
realtime_bi -> StarRocks
federated_query -> Trino
local_analytics -> DuckDB
route realtime_bi@1500ms -> StarRocks budget=1500ms feasible=False
示例的末行说明：调用方要求 1500ms，但 realtime_bi 在规则中目标延迟是 3000ms。路由器仍返回 StarRocks，同时标记 latency_feasible=False，提示上层缩小时间范围、走物化视图或调整 SLA，而非盲目提交慢查询。
12.3.1 查询执行链路的上线准入标准¶
- 权限：查询入口接入统一身份系统，行列级权限以平台策略为准。
- 审计：记录用户、SQL 摘要、引擎、数据集、快照、扫描量、耗时、错误码和结果去向。
- 成本：按用户、团队、工作负载和引擎设置预算；对全表扫描和跨源 Join 做预估拦截。
- 性能：高频查询建立物化视图、结果缓存或预建数据集；探索查询限制并发和扫描量。
- 稳定性：设置超时、取消、连接池上限、并发上限和降级策略。
- 可观测性：连接 DataAgent 调用、SQL 生成、查询执行和结果解释 trace。
- 灾难恢复：核心报表有备份路径和备用引擎；路由规则、权限和 Catalog 配置版本化。
- 数据一致性：生产看板读取发布快照或稳定数据集，不直接读取正在提交的中间表。
12.3.2 查询失败在引擎、权限与数据布局中的定位¶
把 Trino 当成高并发报表数据库¶
- 现象：DataAgent 和 BI 看板共用 Trino，临时跨源查询拖慢固定经营看板。
- 根因：Trino 适合开放湖仓入口和跨源探索，但不负责热点数据物化和报表服务隔离。
- 修复：固定看板迁移到 StarRocks、Doris、ClickHouse 或 Snowflake warehouse；Trino 保留探索入口，并设置并发与扫描量上限。
只看引擎性能，不看数据布局¶
- 现象：压测表现很好，上线后部分查询仍然慢。
- 根因：排序键、分区、物化视图、统计信息和数据倾斜没有按真实查询模式设计。
- 修复：先收集 Top 查询模板，再设计主键、排序键、分区、物化视图和冷热分层，用真实数据分布做回归压测。
多个引擎权限口径不一致¶
- 现象：同一用户在 BI 中看不到某列，在另一个 SQL 客户端却能查到。
- 根因：平台元数据、引擎内部权限和外部 catalog 没有统一发布流程。
- 修复：平台策略优先，自动生成引擎权限配置；新增引擎时先接 Catalog 适配器和策略控制器，再接执行适配器。
本地 DuckDB 分析结果无法复现到生产¶
- 现象：数据科学家在 Notebook 中直接读文件得到结论，生产看板复现时口径不同。
- 根因：本地分析绕过语义层、数据版本和指标口径管理。
- 修复：DuckDB 用于探索，但必须记录输入文件、湖仓快照、SQL 和指标定义；进入生产前转为受治理的数据集或指标层查询。
12.3.3 OLAP 执行结果的证据管理¶
OLAP 查询结果进入 DataAgent 后，就还涉及一次数据库响应。平台需要保存查询文本、参数、引擎、Catalog、快照版本、权限策略、扫描量、返回行数和结果去向。这样用户质疑某个数字时，团队能判断问题来自 SQL 生成、引擎执行、数据布局、权限裁剪还是报告解释。只保存最终表格，会让排查停在“当时查出来就是这个数”。证据管理还要覆盖结果缓存。固定看板和高频问数可以使用缓存，但缓存必须带上语义层版本、数据快照、权限上下文和过期策略。否则同一个自然语言问题可能在不同用户之间复用错误结果，或者在数据刷新后继续返回旧口径。缓存命中不是问题，问题是用户和审计系统不知道命中的是什么版本。多引擎环境下，证据管理尤其重要。Trino、StarRocks、Doris、ClickHouse、Snowflake 和 DuckDB 对 SQL 方言、权限模型和时间函数的处理并不完全一致。DataAgent 不能把“SQL 成功执行”当成最终验收，还要确认执行结果符合语义层口径和用户权限。第34章的 NL2SQL 负责生成查询，第38章的 Trace 负责保存过程，本章的 OLAP 执行契约负责把底层引擎差异收敛成可治理的结果。
多引擎路由上线后，团队要观察每类任务的真实分布。即席问数是否经常退化成明细扫描，报表查询是否绕过物化视图，低优先级任务是否挤占交互式队列，这些都能从查询日志和 Trace 中看到。发现问题后，修复点可能在语义层，也可能在路由策略或表设计。OLAP 层还要向 Agent 返回可理解的失败。超时、权限不足、扫描量超限、快照不存在和语法错误，对 Planner 来说是不同信号。只有错误类型明确，Agent 才能选择改写 SQL、请求澄清、降级到聚合指标，或把问题交给人工。最终，湖仓引擎不是被动执行 SQL 的黑盒。它是 DataAgent 的运行保护层，负责把自然语言带来的不确定性压到可管理范围内。没有这层保护，模型越会生成查询，平台越容易被错误查询拖垮。
查询执行前的预估很关键。平台可以在真正提交前估算扫描分区、读取列、Join 规模和结果行数。超过阈值的查询进入澄清、降级或审批，而非直接占用资源。预估不一定完全准确，但它能把明显失控的查询挡在执行层外。执行后的反馈也要回到 Planner。若查询因为扫描量超限失败，Planner 可以尝试缩小时间窗口；若因为权限不足失败，应请求用户换口径或申请权限；若因为引擎繁忙失败，可以排队或切换到离线引擎。错误信息越结构化，Agent 越可能采取正确恢复动作。物化视图和预聚合需要被语义层知道。很多经营问题并不需要扫明细，已有宽表或指标表就能回答。若模型只看到底层明细表，它会生成昂贵 SQL；若语义层暴露合适的指标入口，OLAP 层压力会小得多，回答也更接近业务口径。
多引擎环境还要管理一致性。同一张 Iceberg 表在不同引擎上的函数、时区、类型转换和权限实现可能有差异。一个 SQL 在 Trino 上正确，不代表在 ClickHouse 或 StarRocks 上同义。平台需要把这些差异写进引擎能力描述，并在路由时避开不兼容路径。OLAP 的生产验收可以从几个高风险问题开始：大范围扫描是否被拦截，低权限用户是否被拒绝，慢查询是否能取消，失败是否回写 Trace，重试是否会重复占用资源。通过这些问题，才说明 DataAgent 的 SQL 执行进入了受控系统。查询路由还要考虑用户意图。用户只是想知道“是否下降”，可能聚合表已经足够；用户要求“列出异常订单”，才需要明细查询。Planner 可以表达意图，语义层可以提供候选查询，OLAP 路由器再根据资源和权限决定执行路径。三者协作后，系统会少很多不必要的大查询。
资源隔离要和业务优先级绑定。管理层会议前的经营看板、普通探索式问数、离线评测批跑和开发调试，不应共享同一队列。队列隔离用于防止低优先级查询拖慢高价值流程，不是为了增加架构复杂度。Agent 自动生成 SQL 后，查询数量会增加，资源优先级更需要清楚。结果缓存也要谨慎使用。相同 SQL 在不同数据快照、用户权限和时间语义下可能代表不同答案。缓存命中前要校验数据版本、租户、权限和参数；缓存命中后，也要在回答中保留数据时间。否则系统会用旧结果快速回答新问题，速度提升了，可信度下降了。OLAP 层要给数据团队提供回放能力。某次用户投诉数字错误时，团队需要拿到当时 SQL、引擎、参数、快照、执行时间和结果 artifact。只有这些信息完整，才能判断是模型生成错了、引擎执行错了，还是数据在查询后发生了变化。缺少回放，很多数字争议会陷入口头解释。
引擎选型最后要回到工作负载。Trino 适合联邦和湖仓查询，ClickHouse 适合高并发明细分析，StarRocks 适合低延迟聚合和物化视图场景。企业往往会并存多个引擎，平台价值在于让 Agent 不直接感知复杂性，又能把每类查询送到合适位置。SQL 生成和执行之间可以加入计划审查。平台不必把模型生成的 SQL 直接送给引擎，而是先解析语法树，检查表权限、扫描范围、危险函数、笛卡尔积和导出风险。审查通过后再执行，失败时把结构化原因交给 Planner。这个步骤能把很多资源和安全问题挡在引擎前。查询结果也需要大小控制。模型可能请求返回明细，实际结果有数百万行；前端和模型都不适合接收这么大结果。执行层可以返回聚合摘要、分页 artifact 或要求用户缩小范围。结果大小控制同时保护系统，也避免模型基于过大样本做不稳定解释。OLAP 层的 SLO 要按任务定义。交互式追问需要秒级反馈，异步报告可以等待更久，评测批跑可以排队。把所有查询都要求低延迟，会导致成本过高；把所有查询都放进离线队列，又会破坏用户体验。SLO 分层能让资源和业务价值对齐。
12.4 OLAP 口径漂移与查询证据¶
OLAP 系统支撑 DataAgent 时，指标口径漂移会直接影响用户信任。同一个“销售额”可能因为退货处理、税费口径、渠道归属、时间分区、汇率折算变化而产生不同结果。传统 BI 场景中，用户可以通过报表说明慢慢校准；Agent 场景中，系统会把查询结果转成自然语言结论，口径差异更容易被读者当成事实冲突。平台需要把 OLAP 口径变化和查询证据绑定起来。
每次指标变更都应留下语义层版本、SQL 片段、数据快照范围、影响报表、影响 Agent 样本和生效时间。DataAgent 回答时，应能引用当时的指标版本和查询证据。若用户复盘历史问题，平台要解释“当时的结果”来自哪个口径，而不是用当前口径重新计算后覆盖历史。这样 OLAP 查询才能成为可追溯证据，而不是一次临时计算。
口径漂移复盘还要关注查询性能。为了修正指标而增加复杂 join、窗口函数或大范围扫描，可能让 Agent 延迟和成本上升。数据团队、平台团队和业务 owner 应共同评估：是否需要预聚合，是否需要新增物化视图，是否需要限制自然语言查询范围，是否需要提示用户切换到异步报告。OLAP 的工程质量，最终会体现在 Agent 回答是否稳定、可解释、可复盘。
12.5 OLAP 查询策略与语义层协同¶
OLAP 层不能独立决定所有查询策略。自然语言问题进入 DataAgent 后，语义层会先给出指标、维度、时间范围和候选数据集，OLAP 层再根据引擎能力、资源队列和权限策略选择执行路径。若语义层没有表达清楚指标口径，OLAP 层即使执行得很快，也可能返回错误答案；若 OLAP 层没有把资源和执行状态反馈回去，语义层也无法知道哪些问题适合改写、降级或转成异步报告。
协同的关键是让计划审查成为正式接口。一个查询计划在提交前，应包含指标版本、候选表、过滤条件、预估扫描量、目标延迟、用户权限和结果规模。语义层负责解释“这个问题应该查什么”，OLAP 层负责判断“这个计划能不能在当前资源和权限下执行”。当计划失败时，返回的原因也要结构化：缺指标、缺权限、扫描量过大、引擎不支持、数据未刷新、结果过大。Planner 拿到这些原因后，才能选择缩小时间范围、换指标入口、请求澄清或进入人工确认。
这层协同还能降低成本。很多自然语言问题看起来需要明细查询，其实只需要已经发布的指标表；很多追问看起来是新问题，其实可以复用同一快照和同一中间结果。语义层保存任务上下文，OLAP 层保存执行证据，两者配合后，系统可以少做重复扫描，也能避免为了追求即时回答而滥用高成本引擎。对早期平台来说，先把查询计划、执行证据和失败原因接成稳定接口，比接入更多 OLAP 产品更重要。
12.6 OLAP 引擎变更的回答一致性检查¶
OLAP 引擎变更后，要检查 DataAgent 回答一致性。把查询从 Trino 切到 StarRocks，或把明细查询改成物化视图，可能让函数语义、时区、空值处理、近似聚合和权限实现发生变化。SQL 仍然成功执行，回答里的数字却可能改变。
一致性检查应选择一组高频业务问题，同时比较旧引擎、新引擎、语义层指标和人工确认结果。若差异来自性能优化，需要说明可接受范围；若差异来自口径变化，要更新语义层版本和用户提示；若差异来自权限实现，要暂停切流。OLAP 切换的验收对象应落到用户最终看到的业务答案，不能停在引擎层。
12.7 OLAP 查询策略的灰度与回滚¶
OLAP 查询策略进入灰度时，变更对象通常会超过引擎本身。一次看似简单的路由调整，可能同时改变资源队列、扫描阈值、物化视图优先级、缓存命中条件、结果分页方式和失败返回码。DataAgent 依赖这些信号判断是否继续追问、是否改写 SQL、是否请求人工确认，因此查询策略发布要按照业务域、租户、指标组和任务类型逐步放量。灰度期间，平台应同时保存旧策略和新策略的执行证据，比较最终业务答案、扫描成本、延迟、失败类型、缓存复用和用户追问比例。只有这些指标稳定，才能说明策略变更没有把问题转移到 Planner、语义层或前端解释层。
回滚设计要早于灰度开始。查询策略回滚不能只恢复一段配置，因为新策略可能已经写入缓存、生成报告 artifact、改变中间结果或触发异步任务。平台需要给策略版本、语义层版本、数据快照和缓存条目建立关联。若某个指标组在灰度后出现异常，回滚应能按租户、业务域或指标范围收窄影响，而不是全平台切回旧策略。已经生成的结果也要标记策略版本，避免用户在复盘时把旧策略和新策略下的数字放在一起比较。对高风险经营指标，回滚后还应触发一组历史问题回放，确认回答内容、图表和引用证据都回到可接受状态。
OLAP 策略发布还要给业务方可读的解释。用户不需要知道引擎路由细节，但需要知道为什么同一个问题今天变慢、为什么某个明细查询被转为异步、为什么系统要求缩小时间范围。若平台只返回技术错误，用户会继续换问法，反而制造更多昂贵查询。更合适的做法是把资源限制、权限限制和数据刷新状态翻译成任务级提示，并在 Trace 中保留原始错误。这样前端给用户清楚预期，后台仍能做工程复盘。OLAP 灰度的成败，最终要看 DataAgent 是否还能给出稳定、可解释、可追溯的业务回答。
12.8 查询结果缓存的证据边界¶
OLAP 查询缓存能降低成本和延迟，但在 DataAgent 场景中要特别谨慎。用户追问时，系统可能复用上一轮查询结果；高峰期，平台可能返回已缓存的指标；报告生成时，中间结果可能被多个图表共享。缓存如果没有证据边界，用户看到的数字就可能脱离数据快照、权限范围和指标版本。缓存命中越高，越要解释缓存对应的事实。
缓存证据至少要包含查询语义、SQL、语义层版本、数据快照、权限上下文、生成时间、失效条件和使用场景。若用户权限发生变化，缓存不能继续复用；若指标版本变化，缓存应失效；若底层分区刷新，平台要判断缓存是否仍在可接受时间窗内。对高风险经营指标，缓存结果还应记录是否经过人工确认或报告发布。这样缓存不会把旧事实包装成新回答。
缓存策略也要区分交互和报告。交互式问数可以接受短时间缓存，以减少重复扫描；正式报告应明确绑定快照，不能因为缓存命中而丢失查询证据；探索性分析可以复用中间结果，但要在用户确认前标明草稿状态。不同任务使用同一缓存策略，会在成本和可信度之间制造隐性冲突。平台需要让 Planner 和前端知道当前结果来自实时查询、可接受缓存，还是历史 artifact。
早期可以给 OLAP 查询接口增加 cache_source 和 evidence_scope 字段。cache_source 说明结果来自实时执行、同会话缓存、跨会话缓存或历史报告；evidence_scope 说明结果绑定的数据快照、权限和指标版本。这样第12章的查询性能优化能继续服务 DataAgent 的可信回答，而不会因为追求速度破坏可复盘性。
12.9 OLAP 查询证据与缓存解释¶
OLAP 系统通常会引入预聚合、物化视图、结果缓存和查询改写。对普通 BI 用户来说，这些机制是性能优化；对 DataAgent 来说，它们也是证据来源的一部分。若同一个问题在不同时间得到不同结果，平台需要解释差异来自缓存过期、物化视图未刷新、查询改写、权限过滤，还是源数据变化。只保存最终数值不足以支撑复盘。
查询证据应包含执行路径。Agent 调用 OLAP 工具后，Trace 应记录逻辑 SQL、实际执行 SQL、命中的物化视图、缓存状态、数据时间、权限过滤、返回行数和关键聚合值。若结果来自缓存，系统要知道缓存生成时间和失效规则；若结果来自预聚合，系统要知道预聚合覆盖范围和刷新时间。这样报告层引用数字时，可以说明数字来自哪个数据版本。
缓存解释也要面向用户。低风险看板可以直接展示缓存时间；高风险报告需要判断缓存是否仍在允许窗口内；审批建议通常应使用最新可验证数据，或者明确进入等待状态。早期可以给 OLAP 工具返回 freshness_status、cache_source 和 evidence_ref 三类字段。这样性能优化不会削弱证据链，反而能让 Agent 更清楚地说明数字来源。
12.10 OLAP 查询层的变更防线¶
OLAP 查询层进入生产后，平台需要把查询模板、物化视图、指标口径、权限过滤、缓存策略、慢查询样本和回滚方式放进统一证据口径。证据口径会减少事后解释成本，让业务、平台、数据、安全和运营团队能够围绕同一组事实讨论问题。没有这些材料，故障发生后只能凭经验判断；有了这些材料，团队可以知道哪些输入有效、哪些动作已经执行、哪些产物可以继续使用、哪些结果需要撤回。
这类证据应和第33章语义层、第34章 NL2SQL 和第41章成本治理连起来。上游章节提供能力基础，下游章节使用运行结果，本章则负责说明中间环节如何被验证。若某个能力只在本章看起来完整，却无法进入 Trace、Eval、发布记录或合规证据包，生产系统仍然会出现断点。读者在实现时应把章节之间的接口看成工程契约，而不是阅读顺序上的相邻关系。
常见风险包括缓存命中过期口径、物化视图刷新失败、权限过滤只在前端执行、查询优化改变结果顺序。这些问题通常不会在一次成功演示中暴露，因为演示样本往往干净、短小、路径明确。真实业务会带来旧数据、异常输入、权限变化、用户撤回、预算限制和长时间运行状态。平台如果没有把这些情况纳入样本和台账，后续扩展场景时就会重复遇到同类问题。
数据平台团队应把 OLAP 变更纳入样本回放，确认速度提升没有牺牲口径和权限。执行记录至少要说明 owner、版本、样本、影响范围、处置动作和复查时间。记录不需要写成流程报告，但要足够让后来者理解当时的判断。对于高风险能力，还应说明哪些条件满足后才能扩大使用，哪些条件失败时必须降级或撤回。
落地时可以先选择少量代表场景建立这种习惯。实践上，应先把高频、高风险、外部可见的路径做扎实，再把样本、台账和复盘方式复制到其他能力中。这样做能让能力说明落到接入、验证、运营和退出，而不是停留在概念描述。
本章小结¶
湖仓表格式解决数据资产开放性，OLAP 引擎解决分析查询性能、并发、服务化和成本问题。Databricks 和 Snowflake 更偏平台化与托管数仓；Doris、StarRocks、ClickHouse 更偏实时 OLAP；Trino 更偏联邦查询；DuckDB 更偏本地分析。多引擎协同依赖统一 Catalog、权限、审计、成本预算、查询状态和失败恢复，而非产品数量。DataAgent 接入湖仓时必须走受控查询接口，不能绕过平台策略直接生成任意 SQL 访问底层引擎。mini-platform 的 route_query 只做早期规则路由，真实生产还需要执行适配器、权限同步和查询观测。
参考文献¶
DuckDB. (n.d.). Documentation.
Trino. (n.d.). Documentation.
ClickHouse. (n.d.). Documentation.
Apache Doris. (n.d.). Documentation.