looker-performance-optimizer

Looker 性能优化器

此主开发者技能规范了新建或现有 Looker 项目中查询性能审计、诊断和优化的整个生命周期。它强制要求采用性能优先的设计、与数据库缓存保持一致、策略性地物化数据，并使用并行子 Agent 和 Looker MCP 工具进行高级 SQL 性能分析。

在此技能下开发的所有优化都必须与数据库方言无关、提高数据库效率，并保留现有业务逻辑的完整性。

---

1. 运行模式（预防式与响应式）

此技能以两种不同模式运行，以应对开发生命周期不同阶段的性能问题：

模式 A：设计即高性能（预防式工程）

向现有项目添加新的探索、视图或持久派生表（PDT）时，使用此模式。Agent 必须确保从一开始就将性能纳入设计：

1. 正确的联接基数：立即声明精确的联接关系（many_to_one、one_to_one），以防止编译器触发对称聚合。
2. PDT 索引与分区：每个新的 PDT 定义必须根据最常用作仪表板筛选条件的字段声明分区键和聚簇键/索引键。
3. 与 ETL 对齐的缓存：每个新探索必须分配到由 ETL/ELT 元数据查询触发的集中式 datagroup，避免使用任意的 persist_for 时间窗口。

模式 B：主动性能调优（响应式存量项目）

在生产环境中诊断和优化运行缓慢的仪表板或探索时，使用此模式。Agent 必须执行以下 5 阶段性能流程：

1. 外观审计与基线测量：切换到开发者模式，并通过 Looker MCP 或 CLI 对运行缓慢的仪表板图块进行基线测试。记录查询运行时间、查询 ID 和数据库成本（扫描字节数/使用的槽位数）。
2. 并行查询分析（借助子 Agent）：启动专用子 Agent，分析生成的 SQL 并并行运行 EXPLAIN 计划，以确定数据库瓶颈（委派规则见第 6 节）。
3. 精准性能重构：对 LookML 层进行有针对性的局部修改：
   • 对齐缓存 datagroup。
   • 将繁重的转换物化为 PDT（遵循 PDT 决策矩阵）。
   • 修正联接关系并实施联接剪枝。
4. 验证与差值测量：重新运行编译器（health_analyze）以确保没有语法错误，重新执行查询，并记录性能改进矩阵。
5. 安全部署到生产环境：将经过优化和验证的 LookML 分支部署到生产环境。

---

2. 缓存与 ETL 对齐规则

调整缓存是降低数据仓库成本、加快仪表板加载速度最快的方法。

• 禁止使用任意持久化时间：在生产环境的探索中使用普通的 persist_for: "24 hours" 或类似的固定时长，严格禁止。这会导致数据过时，并产生冗余且昂贵的数据库查询。
• 必须使用 Datagroup：所有探索必须继承模型文件中定义的集中式 datagroup 缓存策略。
• 由 ETL 触发缓存：Datagroup 必须由 sql_trigger_value 查询触发，该查询会监控数据仓库的实际数据刷新频率（例如，查询 ETL 元数据表或检查 MAX(created_at)）。
• 缓存失效保护措施：设置合理的 max_cache_age（例如，24 小时）作为备用方案，以便在 ETL 流水线未能更新时缓存最终过期，确保用户不会看到极度过时的数据。

---

3. 持久派生表（PDT）物化规则

当复杂联接和行级转换的即时 SQL 编译耗时过长时，必须将数据物化到持久派生表（PDT）中。

A. 主 PDT 决策矩阵

在将视图或 explore 转换为 PDT 之前，Agent 必须根据以下四象限决策矩阵评估查询：

指标 / 象限	物化为 PDT	保留为实时查询
1. 复杂度	查询执行大量转换（例如，复杂的正则表达式、字符串解析、窗口函数）或包含多层联接，执行时间超过 10 秒。	查询只执行简单筛选和清晰的索引联接，执行时间少于 3 秒。
2. 使用频率	explore/dashboard 至关重要、并发量高，且业务用户每天会打开数百次。	高级数据分析师偶尔使用该 explore 进行临时深入分析。
3. 数据新鲜度	业务要求每小时、每天或近实时更新，适合标准重建计划。	业务要求绝对实时、精确到秒的数据新鲜度。
4. 表大小	底层原始表非常庞大（超过 5,000 万行）且缺少分区索引。	底层表较小（少于 1,000 万行）且索引完善。

B. PDT“冷启动”加载协议

为防止大型历史 PDT（尤其是增量 PDT）在首次加载时因数据库超时、资源耗尽或槽位限制而崩溃，Agent 必须执行以下缓解协议：

1. 限制历史数据（分阶段加载）：在初始 LookML PDT 定义中，使用条件日期筛选器临时限制历史查询（例如，只查询最近 30 天的数据）。这可确保数据库在数秒内成功创建物理表。
2. 增量回填（引导并扩展）：创建初始表后，以编程方式按可控批次逐步向前扩展历史筛选范围（例如，按月回填），构建完整历史数据，同时避免因单次超大型事务而崩溃。
3. 试运行成本估算：在构建大型 PDT 之前，调用 Looker MCP 的 query 或 query_sql 工具，试运行扫描字节数估算，以确认是否会超出数据库连接查询限制。
4. 架构卸载（外包 ELT）：如果历史数据集过于庞大，无法在 Looker 的 PDT 层中编译或回填，Agent 必须指示开发者将物化任务卸载到数据库仓库层（使用 dbt、计划查询或数据库物化视图），并将 Looker 映射为标准只读视图。

---

4. LookML 语义重构规则

优化语义建模层可消除编译器导致的冗余，并确保数据库只处理必要的最少数据。

• 消除对称聚合：确保准确声明联接关系（relationship）。如果联接定义为 many_to_one，实际行为却是 one_to_many，Looker 编译器会在 SQL 中注入开销很大的 _distinct 聚合函数（例如，SUM_DISTINCT、AVG_DISTINCT），导致性能大幅下降。
• 裁剪联接：构建 explore 时，应确保 Looker 只联接用户所选字段实际查询的表。利用 required_joins 参数严格控制联接路径。
• 禁止在 SQL 中使用复杂的 Liquid 循环：严禁在 sql: 参数中编写复杂的 Liquid 条件循环，以免编译生成庞大的 SQL CASE WHEN 链。这些链无法由数据库引擎建立索引，并会导致全表扫描。应改用简洁的 LookML 维度或预计算的 PDT 列。

5. Looker CLI 与 MCP 诊断矩阵

要诊断查询性能并运行执行计划，AI Agent 必须使用 Looker CLI 或 Looker MCP 服务。对于程序化数据库内省，优先使用 Looker MCP。

性能操作	Looker CLI 命令	Looker MCP 工具
获取生成的 SQL	looker-cli api query query <id> --fields sql	query(query_id) 或 query_sql
运行查询（测试）	looker-cli api query run_query --query_id <id>	query 或 run_dashboard
检查查询状态	looker-cli api query query_task ...	health_pulse 或 health_analyze
数据库内省	looker-cli api metadata connection_columns <conn> --schema_name <schema> (另请参阅：connection_tables、connection_schemas、connection_databases)	get_connection_table_columns (另请参阅：get_connection_tables)
LookML 编译检查	looker-cli project validate <id>	health_analyze

---

6. AI Agent 执行与子 Agent 委派指南

为提高执行速度、避免令牌膨胀，并防止触及 Agent 环境中的轮次或上下文限制，请遵循以下执行策略：

1. 并行查询分析与上下文隔离（强制）

诊断多个缓慢的仪表板查询会产生大量 SQL 语句、数据库执行计划和 JSON 负载。为保持主开发对话整洁且节省成本，主 Agent 必须委派诊断工作：

1. 识别缓慢图块：列出目标仪表板上所有缓慢的可视化图块。
2. 启动 SQL 分析子 Agent：针对识别出的每个缓慢的 Explore 或图块，启动一个专门的“SQL 分析子 Agent”并行运行。
3. 子 Agent 诊断任务：
   • 通过 Looker MCP 获取生成的 SQL。
   • 直接针对目标连接执行 EXPLAIN 或 EXPLAIN ANALYZE 查询。
   • 解析执行计划，找出确切的瓶颈（例如，全表扫描、缺少索引或对称聚合）。
   • 编写一份精简性能报告，内容必须恰好包括：
     • 有问题的 SQL 片段。
     • 已识别的瓶颈。
     • 确切且可执行的 LookML 修复措施（例如，添加缓存 datagroup、修正 join 关系或创建增量 PDT）。
   • 将精简后的发现报告给主 Agent，然后自行终止。
4. 精简整合：主 Agent 仅接收子 Agent 提供的精简且高度可执行的报告，并协调重构，从而让主对话完全避免出现原始数据库计划转储。

2. 手术式修改规则（禁止完整重写）

为保护开发者注释、保留自定义维度并提高 API 令牌效率，Agent 必须遵守以下手术式编辑规程：

• 禁止完整重写：在对现有 LookML 文件进行任何性能重构或调优时，Agent 不得从头重写、重新生成或重构整个文件。
• 定向替换代码块：Agent 必须进行手术式的局部代码块替换（例如，查找并替换、针对特定行的编辑或定向工具调用），仅修改需要优化的特定 joins、datagroups 或 SQL 参数。
• 保留内容：无关的维度、度量、Explore joins 以及开发者编写的注释必须保持完全不变。