Skip to content

[FEATURE] 查询执行层优化:max_rows 下推、memory_peak SQL 重写、模板缓存与连接复用(子任务 #72-4) #76

Closed

Description

@codeasier

功能描述

查询执行层有四处可优化点:结果切片在 Python 层、memory_peak SQL 嵌套子查询、Jinja 模板无编译缓存、MCP 场景连接未复用。本 issue 是 #72 的子任务,聚焦「查询层执行效率」。

使用场景

  • pt-snap query 大结果集查询(如 leak_detection 返回上万行)
  • pt-snap report peak-memory 调用 memory_peak 模板
  • MCP server 长驻进程中反复执行查询模板

期望的实现方式

1. max_rows 在 Python 层切片而非 SQL LIMIT【中】

QueryService.execute_query 先 executor.execute_template 拉全部行(cursor.fetchall() + 构造 dict 列表),再用 rows[:max_rows] 切。对大结果集是双倍内存 + 全量扫描。

建议:把 max_rows 通过模板变量注入到 SQL 末尾的 LIMIT,下推到 SQLite。

实现要点:

  • QueryExecutor.render 增加可选的 max_rows 参数,渲染时在 SQL 末尾追加 LIMIT {{ max_rows }}(当 max_rows > 0 时)。
  • 注意 active_blocks_at_event 模板已自带 LIMIT {{ limit }},需避免重复 LIMIT。可在模板侧统一约定:所有模板都通过 limit 变量控制,QueryService 不再单独切片。
  • leak_detection / block / event / allocation 模板需要补充 LIMIT 子句(或由 executor 统一追加)。

涉及代码:

  • src/pt_snap_cli/core/query_service.py:execute_query
  • src/pt_snap_cli/query/executor.py:execute / execute_template / render
  • 各 src/pt_snap_cli/query/templates/**/*.yaml

2. memory_peak 模板嵌套子查询【中】

memory_peak.yaml 有 6 个嵌套子查询,每个子查询全表扫描一次,外层再扫一次,总计约 12N 次行扫描(无索引时)。

建议:用 CTE 把峰值计算收敛到一次扫描:

WITH peaks AS (
  SELECT MAX(allocated) AS pa, MAX(active) AS pac, MAX(reserved) AS pr
  FROM {{ device_trace_table }}
  {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% endif %}
  {% if end_id is not none %}{% if start_id is none %}WHERE{% else %}AND{% endif %} id <= {{ end_id|int }}{% endif %}
)
SELECT pa,
  (SELECT MIN(id) FROM {{ device_trace_table }} WHERE allocated = pa) AS peak_allocated_event_id,
  pac,
  (SELECT MIN(id) FROM {{ device_trace_table }} WHERE active = pac) AS peak_active_event_id,
  pr,
  (SELECT MIN(id) FROM {{ device_trace_table }} WHERE reserved = pr) AS peak_reserved_event_id
FROM peaks

注意:配合 #72-1 的索引(allocated / active / reserved),子查询可走索引。需保证 CTE 版本与原版本在边界条件(start_id / end_id 为 null)下输出完全一致。

涉及代码:src/pt_snap_cli/query/templates/statistical/memory_peak.yaml

3. Jinja 模板无编译缓存【低】

QueryExecutor.render 每次 self._env.from_string(template.query) 重新解析模板字符串。CLI 单次调用影响小,MCP 反复调用有累积开销。

建议:在 QueryExecutor 上维护 self._compiled: dict[str, Template],按 template name 缓存编译结果。或用 Environment.from_string 配合 jinja2.FileSystemBytecodeCache。

涉及代码:

  • src/pt_snap_cli/query/executor.py:render / __init__

4. MCP 场景下连接未复用【低】

QueryService.execute_query 每次新建 Context → 新建 sqlite 连接 → 关闭,并重复做 schema 校验(dictionary 表检查)和 device discovery。MCP server 长驻时反复 open/close。

建议:在 SnapshotAnalyzer(api.py)或 QueryService 中按 db_path 缓存 Context 实例。需注意:

  • db 文件被替换(重新 import)后需失效缓存,可通过文件 mtime 或显式 invalidate() 控制。
  • 只读连接复用是安全的(无并发写入)。
  • 缓存应限制大小(如 LRU,maxsize=4),避免内存泄漏。

涉及代码:

  • src/pt_snap_cli/core/query_service.py:execute_query
  • src/pt_snap_cli/context.py:Context
  • src/pt_snap_cli/api.py:SnapshotAnalyzer

验收标准

  • max_rows 通过 SQL LIMIT 下推,不在 Python 层切片
  • active_blocks_at_event 等已有 LIMIT 的模板不出现重复 LIMIT
  • memory_peak 模板用 CTE 重写,扫描次数从 12N 降到常数次
  • CTE 版本与原版本输出在 start_id / end_id 各种组合下完全一致
  • QueryExecutor 缓存编译后的 Jinja 模板
  • SnapshotAnalyzer / QueryService 缓存 Context,db 替换时正确失效
  • 现有测试全部通过,特别是 tests/test_contract_cli_mcp.py 的 CLI/MCP 语义契约
  • MCP 场景下连续执行 10 次查询的累积耗时显著下降

父 issue

#72

Activity

  1. codeasier commented on Jul 27, 2026

    @codeasier
    OwnerAuthor

    代码已逐条核查,以下是对四个优化点的评审意见。


    问题 1:max_rows 在 Python 层切片 — 属实,但方案需调整

    core/query_service.py:128-131 确认先 fetchall() 再 rows[:max_rows],大结果集确实存在双倍内存问题。

    但下推 SQL LIMIT 不能直接替代当前实现,原因在于 QueryResult 设计了两个语义不同的字段:

    # core/models.py:57-61
    @dataclass(frozen=True)
    class QueryResult:
        total: int      # 未截断前的全量行数
        returned: int   # 实际返回行数

    total 在 MCP 场景下有明确用途(让调用方知道结果集实际有多大)。若把 LIMIT 推入 SQL,要么丢失 total 精度,要么需额外发一次 COUNT(*) 查询。

    此外 statistical/active_blocks_at_event.yaml:73 已经有 LIMIT {{ limit|int }}(default=-1 即无限),executor 层再追加一个 LIMIT 会生成两个 LIMIT 子句,SQLite 会直接报语法错误。

    建议:先明确 total 字段的语义取舍(是否接受退化为「已返回行数」,或补一次 COUNT(*)),并在 executor 层检测模板是否已含 LIMIT,不宜统一无条件追加。


    问题 2:memory_peak 嵌套子查询 CTE 重写 — 属实,但提案 CTE 有语义 Bug

    实际模板是 9 个全表扫描子查询(3 个 MAX + 3 对 MAX + MIN(id)),不是「约 12N」。

    更关键的是,提案 CTE 中事件 ID 查询丢失了 start_id/end_id 范围过滤:

    -- 提案写法,缺少范围条件
    (SELECT MIN(id) FROM {{ device_trace_table }} WHERE allocated = pa) AS peak_allocated_event_id

    当同一峰值在范围外也出现时,返回的 event_id 会指向范围外的行。用实际数据验证(range = [3, 5],id=1 与 id=4 的 allocated 同为 500):

    原版本:   peak_allocated_event_id = 4   正确
    提案 CTE: peak_allocated_event_id = 1   错误,落在范围外
    

    这一点直接违反验收标准中的「CTE 版本与原版本输出在 start_id / end_id 各种组合下完全一致」。正确写法需在事件 ID 子查询里保留范围条件:

    (SELECT MIN(id) FROM {{ device_trace_table }} WHERE allocated = pa
      {% if start_id is not none %}AND id >= {{ start_id|int }}{% endif %}
      {% if end_id is not none %}AND id <= {{ end_id|int }}{% endif %}
    ) AS peak_allocated_event_id

    CTE 的方向是对的(3 次 MAX 扫描合并为 1 次),但扫描次数只降到「1 次聚合扫描 + 3 次事件 ID 查找」,不是「常数次」意义上的一次;事件 ID 查找能否走索引取决于 #72-1 是否已落地。


    问题 3:Jinja 模板无编译缓存 — 属实

    query/executor.py:92 每次调用 self._env.from_string(template.query),无复用。

    需补充一点:CLI 是单次进程,每次调用都会重建 QueryExecutor(core/query_service.py:115-117 在 execute_query 内构造),所以此处缓存对 CLI 零收益,仅 MCP 长驻进程有实际意义。按 template name 加一个 dict 缓存即可,FileSystemBytecodeCache 对此场景过重。


    问题 4:MCP 场景连接未复用 — 属实,且比描述的更严重

    除了跨调用每次新建 Context,Context.connect()(context.py:106-125)在 finally 里调用 self.close(),因此即使在单次 execute_query 内,schema 校验(_validate_schema)和实际查询也各自开关一次连接,即同一次查询打开两次连接。

    在 SnapshotAnalyzer / QueryService 层按 db_path 做 LRU 缓存(maxsize=4,按 mtime 失效)方向合理,但必须先处理 Context.connect() 的关闭语义:缓存的 Context 若仍走 finally: self.close() 路径,下次复用时连接已关闭。实现时需要把「单次查询用完即关」与「长驻缓存持有」的连接生命周期分开。


    小结:四条问题均属实,优先级排序也合理。但问题 2 的 CTE 提案存在可验证的语义错误,问题 1 的 SQL 下推需先厘清 total 字段取舍,问题 4 需先解决 Context.connect() 的关闭语义。建议这三点在动手前先定稿。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions