Visualizador de plano de consulta

Use o visualizador de plano de consulta na extensão PostgreSQL para inspecionar a saída do PostgreSQL EXPLAIN sem sair do seu editor. Pode gerar um plano a partir do editor de consultas ou do painel Resultados de Consultas do PostgreSQL, ou abrir no editor a saída de plano existente em JSON ou TEXT. O visualizador funciona da mesma forma no Visual Studio Code e Cursor.

Pré-requisitos

  • Extensão PostgreSQL instalada.
  • Uma ligação ativa a um servidor PostgreSQL se quiser gerar um plano em tempo real a partir do editor de consultas ou do painel de Resultados de Consultas PostgreSQL.
  • Assistente de IA opcional se quiseres análise assistida por IA: instala o GitHub Copilot no Visual Studio Code, ou usa a IA integrada no Cursor.
  • A saída opcional EXPLAIN já está aberta no editor se quiser importar um plano guardado sem se ligar a uma base de dados.

Escolha como abrir um plano

Use o ponto de entrada que corresponda ao seu fluxo de trabalho:

  • Editor de consultas: Selecione Visualizar Plano de Consulta (PostgreSQL) na barra de ferramentas do editor. Se não selecionares texto primeiro, a extensão usa o conteúdo atual do editor.
  • Painel de Resultados da Consulta PostgreSQL: Execute uma consulta e selecione Visualizar o Plano de Consulta na barra de ferramentas do painel de Resultados da Consulta PostgreSQL para inspecionar a consulta que produziu esse conjunto de resultados.
  • Plano importado: Abra qualquer separador do editor que contenha a saída do plano PostgreSQL, depois execute o PGSQL: Visualize Query Plan from Editor a partir da Paleta de Comandos.

Gerar um plano a partir de uma consulta em tempo real

  1. Abra o ficheiro SQL que quer inspecionar no editor de consultas.
  2. Estabelece ligação à base de dados de destino.
  3. Selecione a declaração que pretende analisar. Se deixares a seleção vazia, a extensão usa o conteúdo atual do editor.
  4. Selecione Visualizar Plano de Consulta (PostgreSQL) na barra de ferramentas do editor. Também pode executar a consulta primeiro e depois selecionar Visualizar Plano de Consulta no painel de Resultados da Consulta PostgreSQL .
  5. Em Configurar Plano de Consulta, escolhe o formato e as opções que queres, e depois carrega em Enter.
  6. Revê o plano no visualizador.

Configurar opções de plano de consulta

O seletor Configure Query Plan permite-lhe escolher o formato de saída e as opções EXPLAIN a utilizar.

Option O que muda
JSON Fornece um resultado estruturado do plano que funciona melhor em todas as visualizações.
TEXTO Devolve a saída em texto EXPLAIN simples do PostgreSQL e preserva essa fonte na Vista de Fonte.
ANALISAR Executa a consulta e inclui estatísticas reais do tempo de execução.
BUFFERS Adiciona estatísticas de utilização do buffer. Selecioná-la ativa automaticamente ANALYZE.
TEMPORIZAÇÃO Adiciona dados reais de temporização. Selecioná-la ativa automaticamente ANALYZE.
WAL Adiciona estatísticas de utilização do WAL. Ao selecioná-la, ativa automaticamente ANALYZE.
VERBOSO Adiciona detalhes adicionais na saída, como informações sobre o esquema e as colunas.
CUSTOS Inclui valores estimados de arranque e custos totais.
CONFIGURAÇÕES Inclui definições do planificador que diferem das predefinições.

Atenção

EXPLAIN ANALYZE Executa a consulta. Se a instrução modificar dados, como INSERT, UPDATE, DELETE, ou TRUNCATE, a extensão mostra um prompt de confirmação antes de continuar.

Abra um plano guardado no editor

  1. Abra um separador de editor que contenha a saída do PostgreSQL EXPLAIN em formato JSON ou TEXTO.
  2. Abra a paleta de comandos (Ctrl+Shift+P).
  3. Executar PGSQL: Visualizar o Plano de Consulta a partir do Editor.
  4. Revê o plano importado no visualizador.

Este fluxo de trabalho não requer uma ligação ativa à base de dados. O comando lê o conteúdo atual do editor, por isso podes usá-lo com a saída do plano copiada, ficheiros .json ou .txt guardados, ou texto do plano colado num editor temporário.

Alternar entre vistas

Use o seletor de vista na barra de ferramentas para alternar entre Vista em Árvore, Vista Icicle, Vista de Tabela e Vista de Fonte.

Vista da árvore

Vista em árvore abre-se por predefinição. Usa-o quando quiseres um diagrama nó a nó do plano de execução.

  • Use os controlos de zoom para aproximar, afastar o zoom, reiniciar a vista ou ajustar o plano à janela.
  • Utilize o painel de opções para alterar a direção do esquema e a métrica de cor que destaca nós dispendiosos ou invulgares.
  • Selecione um nó para abrir o painel de detalhes.
  • Clique com o botão direito num nó para saltar para outra vista ou analise esse nó com o assistente de IA.

Vista de tabela

Usa a Vista de Tabela quando quiseres ordenar, pesquisar e comparar vários nós ao mesmo tempo.

  • O plano é achatado numa mesa ordenável em vez de uma árvore dobrável.
  • A caixa de pesquisa aparece apenas na Visualização de Tabela.
  • A pesquisa encontra correspondências no tipo de nó, nome de relação, nome de índice, pseudónimo, texto do filtro e nome do subplano.
  • Use o seletor de predefinição para se focar em Desempenho, Estimativas, Eficiência ou I/O, ou personalize as colunas visíveis da métrica.

Vista do Pingente de Gelo

Use o Icicle View quando quiser um resumo visual completo de onde se concentra o custo, o tempo ou a utilização do buffer.

  • A Vista de Icicle é uma vista separada, não um painel dentro da Vista da Árvore.
  • Usa o painel de opções para mudar predefinições, alterar a métrica de largura, alterar a métrica de cor e alternar entre o âmbito próprio e total onde for suportado.
  • Passe o rato sobre um bloco para inspecionar as suas métricas, ou clique com o botão direito num bloco para abrir detalhes ou mover para outra vista.

Vista de Origem

Utiliza Vista da origem quando pretenderes o resultado original do plano.

  • Selecione Opções para alternar entre o modo Árvore e o modo Texto.
  • O painel mostra se a fonte importada ou gerada é JSON ou TEXTO.
  • Expandir Tudo e Colapsar Todos aparecem apenas na barra de ferramentas enquanto a Vista de Fonte estiver ativa.
  • No modo Texto, o plano abre num editor só de leitura. No modo Árvore , podes inspecionar a estrutura analisada como uma árvore dobrável.

Selecione Copiar Plano a qualquer momento para copiar a fonte atual do plano para a prancheta. Os planos JSON são copiados em formato formatado, e os planos TEXT são copiados como fonte original.

Examinar os nós do plano

Selecione um nó na Vista em Árvore, Vista de Tabela ou Vista Icicle para abrir o painel de detalhes.

  • General mostra o tipo de nó, as métricas principais e os detalhes de análise específicos do plano.
  • E/S aparece quando o plano inclui dados em memória intermédia.
  • Condições aparece quando o nó expõe filtros, condições de junção ou predicados semelhantes.

Utilize este painel para comparar o trabalho estimado com o trabalho real, inspecionar nós com utilização intensiva de buffers e confirmar que predicados determinam o plano.

Analise planos com o assistente de IA

Utilize o assistente de IA quando quiser que a extensão abra um chat de análise tendo como contexto o plano atual.

Analise o plano completo

  1. Abrir o plano no visualizador.
  2. Selecione Analisar com Copilot (ou Analisar com IA no Cursor).
  3. Escolha se inclui o texto da sua consulta SQL com a análise.
  4. Revise a nova sessão de chat que abre no modo Agente.

Se o plano veio do PGSQL: Visualize Query Plan from Editor e ainda não existe texto SQL útil, a extensão pode pedir-te para introduzires a consulta primeiro para que a IA tenha melhor contexto.

Analisar um nó

  1. Clique com o botão direito no nó que pretende inspecionar.
  2. Selecione Analisar este nó com o Copilot (ou Analisar este nó com inteligência artificial no Cursor).
  3. Revise a nova sessão de chat do modo Agente para análise específica de cada nó.

Controlar se o texto SQL está incluído

A pgsql.copilot.autoAttachQuery definição controla como a extensão gere o texto SQL quando lança análises de IA:

  • Pergunte se deve incluir SQL cada vez
  • Inclua sempre SQL sem necessidade de pedir
  • Nunca inclua SQL

Quando escolhe incluir ou excluir SQL do prompt, a extensão pode também dar-lhe a opção de memorizar essa escolha para futuras sessões.

Use a ferramenta de plano de consulta no modo Agente

O visualizador coloca em cache o plano atual e disponibiliza-o ao assistente de IA através da ferramenta pgsql_query_plan, ou do equivalente MCP nos hosts suportados. Essa ferramenta apoia estas ações:

Ação Usa-o para
get_summary Obtenha um resumo geral do plano antes de entrar em detalhes.
get_node Inspeciona um nó por ID.
get_subtree Inspecionar um nó juntamente com os seus descendentes.
list_nodes Encontre nós por tipo ou custo mínimo.

Se quiser que a IA comece pela consulta ativa em vez do visualizador, use Analisar o Desempenho da Consulta no submenu de Ações de Consulta da IA do editor. Usa o visualizador quando quiseres inspecionar o plano tu próprio primeiro e depois entrega exatamente esse plano à IA.

Dicas para análise de desempenho

  • Use ANALISAR quando for seguro executar a instrução. As estimativas por si só podem esconder pressupostos incorretos quanto à contagem de linhas.
  • Compare as contagens estimadas e reais de linhas para identificar estatísticas obsoletas ou problemas de seletividade de filtros.
  • Mude para a Vista de Tabela quando o plano for grande e precisares de pesquisa ou comparações de métricas lado a lado.
  • Mude para a Vista de Fonte quando precisares do plano bruto para um problema, revisão de código ou discussão com colegas de equipa.

Conteúdo relacionado

  • Last updated on