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.

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:

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

• Editor de consultas e IntelliSense
• Integração com Copilot
• Modo agente
• Referência de comandos
• Referência de definições