查詢計畫視覺化工具

使用 PostgreSQL 擴充套件中的查詢計畫視覺化工具，在不離開編輯器的情況下檢查 PostgreSQL EXPLAIN 的輸出。 你可以從查詢編輯器或 PostgreSQL 查詢結果面板產生計畫，或是從編輯器開啟現有的 JSON 或 TEXT 計畫輸出。 視覺化工具在 Visual Studio Code 和游標中也是一樣的運作方式。

先決條件

  • 安裝了 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執行的選項。

Option 它改變了什麼
JSON 回傳在各種視覺檢視中效果最佳的結構化計畫輸出。
TEXT 回傳 PostgreSQL 的純文字 EXPLAIN 輸出，並將該原始碼保存在 原始碼檢視中。
分析 執行查詢並包含實際執行時統計資料。
緩衝區 新增緩衝區使用統計數據。 選擇後會自動啟用 ANALYZE。
時間點 新增實際的時序資料。 選擇後會自動啟用 ANALYZE。
瓦爾 新增 WAL 使用統計數據。 選擇後會自動啟用 ANALYZE。
冗長 新增額外的輸出細節，如結構與欄位資訊。
成本 包含預估的啟動及總成本值。
設定 包含與預設不同的規劃器設定。

注意事項

EXPLAIN ANALYZE 執行查詢。 若陳述修改資料，如 INSERT、 UPDATE、 DELETE或 TRUNCATE，擴充功能會在繼續前顯示確認提示。

從編輯器開啟已儲存的計畫

  1. 開啟一個包含 PostgreSQL EXPLAIN 輸出的編輯器分頁，格式為 JSON 或 TEXT 格式。
  2. 打開 指令面板 （Ctrl+Shift+P）。
  3. 執行 PGSQL：從編輯器中視覺化查詢計畫。
  4. 在視覺化工具中檢視匯入的計畫。

此工作流程不需要主動的資料庫連線。 這個指令會讀取目前編輯器的內容，所以你可以搭配複製的計畫輸出、儲存 .json 或 .txt 檔案，或貼上到草稿編輯器的計畫文字一起使用。

在視圖之間切換

使用工具列中的檢視選擇器，在 樹狀檢視、 冰柱檢視、 表格檢視和 來源檢視之間切換。

樹狀視圖

樹狀檢視預設會開啟。 當你想要執行計畫的逐節點圖時，可以用它。

  • 使用縮放控制來放大、縮小、重設視角，或將平面圖對準視窗。
  • 使用選項面板來更改版面方向和用來標示昂貴或特殊節點的顏色指標。
  • 選擇節點開啟詳細面板。
  • 右鍵點擊節點可跳到另一個視圖或用 AI 助理分析該節點。

表格檢視

當你想同時排序、搜尋和比較多個節點時，可以使用 表格檢視 。

  • 該方案會扁平化為可排序的表格，而非可展開/摺疊的樹狀結構。
  • 搜尋框僅出現在 表格檢視中。
  • 搜尋匹配節點類型、關聯名稱、索引名稱、別名、篩選文字及子計畫名稱。
  • 使用預設選擇器來專注於 效能、 預估、 效率或 輸入輸出，或自訂可見的指標欄位。

冰柱景觀

當你想以全寬顯示的視覺摘要來查看成本、時間或緩衝區使用集中在哪裡時，請使用 Icicle View。

  • 冰柱視圖 是獨立的視圖，不是樹 狀視圖內的一個窗格。
  • 使用選項面板來切換預設設定、變更寬度指標、變更色彩指標，並在支援的情況下於自身範圍與總範圍之間切換。
  • 將滑鼠移到區塊上查看其指標，或右鍵點擊區塊以開啟詳細資料或切換到其他視圖。

資料來源檢視

想要原始圖紙輸出時，請使用 來源檢視 。

  • 選擇 選項 可在 樹狀 模式與 文字 模式間切換。
  • 面板會顯示匯入或產生的原始碼是 JSON 還是 TEXT。
  • 「全部展開 」和 「全部摺疊」 只會在「 來源檢視 」啟動時才會出現在工具列中。
  • 在 文字 模式中，該計畫會在唯讀編輯器中開啟。 在 Tree 模式中，你可以將解析後的結構以可摺疊的樹狀圖形式查看。

隨時選擇 複製計畫 ，將目前的計畫來源複製到剪貼簿。 JSON 計畫是以格式化形式複製，TEXT 計畫則以原始來源形式複製。

檢視計畫節點

在 樹狀檢視、 表格檢視或 冰柱檢視 中選擇節點以開啟詳細面板。

  • General 顯示節點類型、關鍵指標及計畫專屬分析細節。
  • 當計畫包含緩衝區資料時，I/O 會出現。
  • 條件會在節點顯示出篩選器、聯結條件或類似述詞時顯示。

使用此面板比較估計與實際工作量，檢查緩衝區密集節點，並確認哪些謂詞驅動計畫。

用 AI 助理分析計畫

當你希望擴充功能開啟分析對話，並以目前的方案作為脈絡時，請使用 AI 助理。

分析完整計畫

  1. 在視覺化工具中開啟計畫。
  2. 選擇「用 Copilot 分析」（或在游標中用 AI 分析）。
  3. 請選擇是否將你的 SQL 查詢文字納入分析中。
  4. 查看在特工模式開啟的新聊天會話。

如果計畫是從 PGSQL： Visualize Query Plan from Editor 取得 ，且還沒有有用的 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 。 僅靠估計值就能掩蓋錯誤的列數假設。
  • 比較估計與實際的列數，以找出過時的統計數據或過濾選擇性問題。
  • 當計畫規模較大且需要搜尋或並排指標比較時，請切換到 表格檢視 。
  • 當你需要原始計畫以處理問題、程式碼審查或與團隊討論時，請切換到 Source View 。

相關內容

  • Last updated on