你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

查询计划可视化工具

使用 PostgreSQL 扩展中的查询计划可视化工具检查 PostgreSQL EXPLAIN 输出，而无需离开编辑器。 可以从查询编辑器或 PostgreSQL 查询结果面板生成计划，或者从编辑器中打开现有的 JSON 或 TEXT 计划输出。 可视化工具在Visual Studio Code和 Cursor 中以相同的方式运行。

先决条件

  • 已安装 PostgreSQL 扩展。
  • 如果要从查询编辑器或 PostgreSQL 查询结果面板生成实时计划，请与 PostgreSQL 服务器建立活动连接。
  • 如果需要 AI 辅助分析的可选 AI 助手：在 Visual Studio Code 中安装GitHub Copilot，或使用 Cursor 中的内置 AI。
  • 如果要导入已保存的计划而不连接到数据库，则编辑器中已打开可选 EXPLAIN 输出。

选择如何打开套餐

使用与工作流匹配的入口点：

  • 查询编辑器：在编辑器工具栏中选择 “可视化查询计划”（PostgreSQL ）。 如果不首先选择文本，扩展将使用当前编辑器内容。
  • PostgreSQL 查询结果面板：运行查询，然后在 PostgreSQL 查询结果面板中选择“ 可视化查询计划 ”工具栏，以检查生成该结果集的查询。
  • 导入的计划：打开包含 PostgreSQL 计划输出的任何编辑器选项卡，然后从命令面板运行 PGSQL：可视化编辑器中的查询计划。

从实时查询生成计划

  1. 在查询编辑器中打开要检查的 SQL 文件。
  2. 连接到目标数据库。
  3. 选择要分析的语句。 如果将所选内容留空，则扩展将使用当前编辑器内容。
  4. 在编辑器工具栏中选择 “可视化查询计划”（PostgreSQL ）。 还可以先运行查询，然后在 PostgreSQL 查询结果面板中选择“可视化查询计划”。
  5. 在 “配置查询计划”中，选择所需的格式和选项，然后按 Enter。
  6. 查看可视化工具中的计划。

配置查询计划选项

配置查询计划 选择器可让你选择输出格式以及要运行的 EXPLAIN 选项。

选项 更改的内容
JSON 返回最适用于视觉视图的结构化计划输出。
TEXT 返回 PostgreSQL 的纯文本 EXPLAIN 输出，并在 源视图中保留该源。
分析 执行查询并包括实际的运行时统计信息。
缓冲区 添加缓冲区使用情况统计信息。 选择它会自动启用 ANALYZE。
时间 添加实际计时数据。 选择它会自动启用 ANALYZE。
WAL 添加 WAL 使用情况统计信息。 选择它会自动启用 ANALYZE。
详细 添加额外的输出详细信息，例如架构和列信息。
成本 包括估计的启动和总成本值。
设置 包括不同于默认值的规划器设置。

Caution

EXPLAIN ANALYZE 运行查询。 如果语句修改数据（例如INSERT，UPDATE或DELETETRUNCATE）扩展在继续之前会显示确认提示。

从编辑器中打开已保存的计划

  1. 打开包含 JSON 或 TEXT 格式的 PostgreSQL EXPLAIN 输出的编辑器选项卡。
  2. 打开 命令面板 （Ctrl+Shift+P）。
  3. 运行 PGSQL：从编辑器可视化查询计划。
  4. 在可视化工具中查看导入的计划。

此工作流不需要活动数据库连接。 该命令会读取当前编辑器中的内容，因此您可以将其用于复制的计划输出内容、已保存的 .json 或 .txt 文件，或粘贴到临时编辑器中的计划文本。

在视图之间切换

使用工具栏中的视图选择器在 树视图、 Icicle 视图、 表视图和 源视图之间移动。

树视图

树视图 默认打开。 当需要执行计划的逐节点关系图时，请使用它。

  • 使用缩放控件放大、缩小、重置视图或将计划调整到窗口。
  • 使用选项面板可更改布局方向和突出显示昂贵或异常节点的颜色指标。
  • 选择一个节点以打开详细信息面板。
  • 右键单击某个节点以跳转到另一个视图，或使用 AI 助手分析该节点。

表格视图

如果要一次性对多个节点进行排序、搜索和比较，请使用 表视图 。

  • 该计划被展平为可排序表格，而不是可折叠的树状结构。
  • 搜索框仅显示在 表视图中。
  • 搜索与节点类型、关系名称、索引名称、别名、筛选器文本和子计划名称匹配。
  • 使用预设选择器专注于 性能、 估计、 效率或 I/O，或自定义可见的指标列。

冰柱图视图

当您想通过全宽可视化摘要了解成本、时间或缓冲区使用主要集中在哪些位置时，请使用 Icicle 视图。

  • Icicle 视图 是单独的视图，而不是 树视图中的窗格。
  • 使用“选项”面板切换预设、更改宽度指标、更改颜色指标，并在支持的自范围和总范围之间进行切换。
  • 将鼠标悬停在块上以检查其指标，或右键单击某个块以打开详细信息或移动到另一个视图。

源视图

需要原始计划输出时使用 源视图 。

  • 选择“选项”，以在“树”和“文本”模式之间切换。
  • 该面板显示导入的源还是生成的源是 JSON 还是 TEXT。
  • 仅当源视图处于活动状态时，全部展开和全部折叠才会显示在工具栏中。
  • 在 文本 模式下，计划将在只读编辑器中打开。 在 树 模式下，您可以以可折叠树的形式查看解析后的结构。

随时选择 “复制计划 ”，将当前计划源复制到剪贴板。 JSON 计划会以格式化形式复制，而 TEXT 计划则按其原始内容复制。

检查计划节点

在 树视图、 表视图或 Icicle 视图中 选择一个节点以打开详细信息面板。

  • 常规 显示节点类型、关键指标和计划特定的分析详细信息。
  • 当计划包含缓冲区数据时，会出现 I/O。
  • 当 节点公开筛选器、联接条件或类似谓词时，将显示条件。

使用此面板可以比较估计工作量与实际工作量，检查缓冲区占用较高的节点，并确认哪些谓词在主导该计划。

使用 AI 助手分析计划

当你希望扩展程序以当前计划为上下文打开分析聊天时，请使用 AI 助手。

分析完整计划

  1. 在可视化工具中打开计划。
  2. 选择“使用Copilot进行分析（或在游标中使用 AI 进行分析）。
  3. 选择是否在分析中包含 SQL 查询文本。
  4. 查看在代理模式下打开的新聊天会话。

如果计划来自 PGSQL：从编辑器可视化查询计划 ，但还没有有用的 SQL 文本，扩展可以提示你先输入查询，以便 AI 具有更好的上下文。

分析一个节点

  1. 右键单击要检查的节点。
  2. 选择“使用Copilot分析此节点（或在游标中使用 AI 分析此节点）。
  3. 查看新的代理模式聊天会话，以进行节点特定分析。

控制是否包含 SQL 文本

该 pgsql.copilot.autoAttachQuery 设置控制扩展在启动 AI 分析时如何处理 SQL 文本：

  • 每次都询问是否包含 SQL
  • 始终包含 SQL，无需提示
  • 切勿包含 SQL

当您选择在提示内容中包含或排除 SQL 时，扩展程序还可以提供记住该选择以供将来会话使用的选项。

在代理模式下使用查询计划工具

可视化工具会缓存当前计划，并通过 pgsql_query_plan 工具或受支持主机上的 MCP 等效项将其公开给 AI 助手。 该工具支持以下操作：

Action 将其用于
get_summary 在深入了解详细信息之前，请获取计划范围的摘要。
get_node 通过 ID 查看一个节点。
get_subtree 一起检查节点及其后代。
list_nodes 按类型或最低成本查找节点。

如果希望 AI 从活动查询而不是可视化工具开始，请使用编辑器的 AI 查询操作子菜单中的“分析查询性能”。 如果想要先检查计划，然后再将确切计划交给 AI，请使用可视化工具。

性能分析提示

  • 在安全运行语句时使用 ANALYZE 。 仅估计就可以隐藏错误的行计数假设。
  • 比较估计行计数和实际行计数，以发现过时的统计信息或筛选选择性问题。
  • 当计划较大且需要搜索或并行指标比较时切换到 “表视图 ”。
  • 当你需要查看某个问题、代码评审或与团队成员讨论时所需的原始方案时，请切换到 源视图。

相关内容

  • Last updated on