MongoDB Query Optimizer: meça a consulta antes de criar índice

ANÁLISE EDITORIAL

Uma consulta lenta não se resolve apenas adicionando um índice. Sem observar o plano de execução, os índices existentes, a quantidade de documentos examinados, a frequência da consulta e o custo de escrita, uma sugestão plausível pode duplicar estruturas, aumentar armazenamento e deslocar o problema. A MongoDB Query Optimizer organiza o diagnóstico antes da mudança.

A versão auditada vem do repositório oficial mongodb/agent-skills, mantido pela MongoDB. Ele tinha 175 estrelas na consulta de 27 de agosto de 2026, estava ativo e ficou fixado no commit 6ebabd86ebdbe85f37082e9a7d37e18ebf6ebba0, sob licença Apache-2.0. A adoção fica abaixo da regra geral de mil estrelas, mas a exceção é verificável: o mantenedor é o fornecedor oficial, há versão, documentação e licença explícitas. O pacote local é somente textual.

O que esta Skill faz de verdade

O arquivo principal ensina um agente a diagnosticar consultas MongoDB e propor otimizações com evidência. Para uma consulta específica, a sequência preferida é ler os índices da coleção, obter um explain, observar uma amostra limitada e consultar o Performance Advisor quando a integração Atlas estiver autorizada. Para uma análise geral, a Skill prioriza consultas lentas e recomendações do cluster em vez de adivinhar pelo nome da coleção.

As quatro referências cobrem princípios de índices compostos, consultas cobertas, collation, arrays, regex, paginação, agregações, atualizações e antipadrões. O foco é transformar uma pergunta como “por que esta busca está lenta?” em uma hipótese verificável: qual plano venceu, se houve COLLSCAN ou IXSCAN, quantos documentos e chaves foram examinados, se a ordenação ocorreu em memória e qual índice já existe.

A documentação oficial do resultado de explain deixa um limite importante: o comando ignora o cache de planos e pode escolher entre candidatos sem reproduzir exatamente o estado contínuo da aplicação. A Skill ajuda a medir, mas não transforma uma execução isolada em prova universal.

Para quem serve

Serve a desenvolvedores, DBAs, SREs e equipes de plataforma que investigam buscas, agregações ou atualizações lentas em MongoDB Community, Enterprise Advanced ou Atlas. Também ajuda quem recebeu de uma IA a frase “crie este índice composto” e quer verificar se a ordem dos campos, o padrão de consulta e os índices existentes sustentam a recomendação.

O melhor ponto de partida é uma consulta real com banco, coleção, filtro, projeção, ordenação, limite e frequência conhecidos. Para análise de cluster, entram também projeto, cluster, namespace, período e permissão de observabilidade. O pior ponto de partida é fornecer uma URI completa com senha e pedir “otimize tudo”.

Esta Skill é distinta de materiais do catálogo sobre Redis, PromQL, ES|QL e busca em logs. Ela trata planos de consulta e índices de um banco documental MongoDB. Não configura cache, não escreve métricas e não substitui projeto de esquema, capacidade do cluster ou investigação de código da aplicação.

Compatibilidade e pré-requisitos

O repositório oficial declara uso com Claude Code, Cursor, Codex, GitHub Copilot CLI e VS Code, Gemini e Grok. O README fixado no commit separa o plugin mongodb-atlas, que usa o servidor MCP hospedado e OAuth, do plugin mongodb, voltado a implantações autogerenciadas com servidor MCP local.

• Cliente compatível com Agent Skills e referências relativas.
• Acesso autorizado à implantação MongoDB, preferencialmente somente leitura no primeiro ciclo.
• Banco, coleção e formato completo da consulta quando o problema for específico.
• Índices atuais e explain com queryPlanner ou executionStats.
• Projeto e cluster Atlas quando o Performance Advisor for necessário.
• Ambiente de teste e plano de rollback antes de criar ou remover índice.

O pacote do Bastidores não instala servidor MCP, não conecta banco e não inclui credencial. Sem integração, a Skill ainda pode revisar a forma da consulta, mas deve declarar que não mediu o workload, o plano real nem o impacto.

Instalação recomendada

Para auditoria, baixe o ZIP local e compare seus sete arquivos com o diretório oficial fixado. A licença integral está no pacote e também pode ser conferida no arquivo Apache-2.0 oficial.

1. Extraia o ZIP em uma pasta de revisão fora do projeto produtivo.
2. Leia SKILL.md e as duas referências sempre obrigatórias.
3. Carregue a referência de agregações ou atualizações somente quando o caso exigir.
4. Compare arquivos e commit antes de instalar no cliente escolhido.
5. Configure o acesso ao MongoDB separadamente, com identidade de menor privilégio.

O README também documenta npx skills add mongodb/agent-skills. Esse comando consulta a rede e pode instalar o conjunto de Skills do repositório. Revise destino e diff e mantenha apenas a pasta necessária quando o cliente permitir seleção. O guia oficial de MongoDB Agent Skills deve prevalecer se a forma de instalação mudar.

Configuração antes do primeiro uso

Registre uma ficha mínima: ambiente, versão do MongoDB, banco, coleção, consulta completa, projeção, ordenação, limite, frequência, latência observada, volume aproximado, índices existentes e impacto para o usuário. Em Atlas, acrescente projeto, cluster, namespace e janela temporal.

Não cole a URI de conexão no prompt. Guarde usuário, senha, certificado e parâmetros em configuração protegida do cliente ou do servidor MCP. Se uma amostra de documento for necessária, limite a uma unidade, projete somente campos úteis e remova dados pessoais, segredos e identificadores.

O catálogo oficial de ferramentas do MongoDB MCP descreve operações como collection-indexes, explain e Performance Advisor. Confirme os nomes e parâmetros atuais antes de executar. Permissão para ler planos e índices não autoriza criar, remover ou reconstruir índice.

Primeiro uso seguro

Comece com uma solicitação sem mutação: “Analise esta consulta e seus índices. Rode primeiro queryPlanner, liste lacunas e proponha no máximo uma hipótese. Não crie nem remova índices”. Se a conexão não estiver configurada, forneça a consulta e um explain já sanitizado.

Use queryPlanner para entender a forma do plano. Execute executionStats somente com escopo e timeout compatíveis, pois essa modalidade executa o plano vencedor para coletar estatísticas. A referência oficial do comando explain confirma que operações de escrita explicadas não são aplicadas, mas a consulta avaliada ainda pode consumir recursos.

Confira nReturned, totalDocsExamined, totalKeysExamined, etapas de busca e ordenação. Depois confronte a hipótese com consultas recorrentes, horário, carga e métricas do cluster. Uma coleção pequena pode usar varredura total sem que isso justifique um índice adicional.

Resultado esperado

A primeira entrega deve separar evidência, hipótese e ação. Evidência inclui consulta, índices existentes, plano vencedor, documentos e chaves examinados, quantidade retornada, ordenação e contexto do workload. Hipótese explica por que o plano pode estar caro. Ação propõe teste controlado, não mudança imediata.

Quando um índice composto for indicado, a ordem dos campos precisa ser justificada pelo padrão da consulta. A diretriz oficial Equality, Sort, Range coloca igualdades primeiro e ajuda a decidir entre ordenação e intervalo. Ela é uma diretriz, não uma receita infalível. Um intervalo muito seletivo pode justificar outra ordem.

O resultado também deve registrar efeitos colaterais: espaço em disco, memória, manutenção em cada escrita, tempo de construção, redundância com índices existentes e comportamento em réplicas ou shards. Depois do teste, compare o mesmo formato de consulta e confirme que a melhoria aparece no ambiente relevante.

Permissões e riscos

O ZIP contém apenas Markdown e a licença. O uso funcional pode expor nomes internos, índices, amostras de documentos e logs de consultas lentas. Performance Advisor pode exigir acesso ao projeto Atlas. Conceda somente a permissão necessária e reduza namespaces e período.

• Comece com leitura e não forneça URI ou credencial ao conteúdo da conversa.
• Masque documentos e filtros com dados pessoais ou comerciais.
• Limite find de amostra a um documento e projete poucos campos.
• Defina timeout e período curto para diagnósticos em produção.
• Criação e remoção de índices exigem aprovação separada, teste e rollback.
• Não remova índice apenas porque parece redundante. Exija evidência de uso e recomendação aplicável.

A documentação oficial do Performance Advisor alerta que índices ajudam leituras, mas têm custo de escrita. A página também informa disponibilidade e permissões que variam por tipo de cluster e recurso. Confira o ambiente atual antes de prometer acesso.

Erros comuns

Criar índice sem explain: uma recomendação baseada só na consulta ignora índices existentes, seletividade, tamanho da coleção e plano real. Colete evidência antes da mudança.

Tratar COLLSCAN como falha automática: em coleção pequena ou consulta ampla, a varredura pode ser aceitável. Compare custo, frequência e retorno.

Usar ESR sem contexto: igualdade, ordenação e intervalo ajudam a ordenar campos, mas collation, arrays, projeção e seletividade mudam o resultado. Teste com o workload.

Buscar consulta coberta a qualquer custo: incluir muitos campos no índice aumenta tamanho e custo de manutenção. Uma projeção menor pode ser mais simples do que um índice enorme.

Ignorar a escrita: cada índice precisa ser atualizado em inserções e alterações. O manual oficial de índices deve orientar limites e tipos atuais.

Confundir sugestão com execução: a Skill diz para não criar índices diretamente sem aprovação. Preserve esse ponto mesmo quando a ferramenta conectada oferece mutação.

Versão auditada e download local

A curadoria fixou a versão 1.0.0 no commit 6ebabd86ebdbe85f37082e9a7d37e18ebf6ebba0 de mongodb/agent-skills, consultado em 27/08/2026 com 175 estrelas e licença Apache-2.0. A exceção ao piso de mil estrelas foi aceita porque a Skill é mantida oficialmente pela MongoDB, está ativa e possui documentação e licença verificáveis.

O pacote tem 15.345 bytes e SHA-256 4ec87fae6f076a20bd6481b72e43fd0608385e352e5c3d44aa51fe069220ea93. Baixar o pacote documental auditado. O botão para abrir o repositório oficial fica separado no card da página.

Entradas incluídas: SKILL.md, LICENSE, ORIGEM.md e quatro arquivos em references. Não há servidor MCP, plugin, manifestos, scripts, executáveis, dependências, consultas, dados, chaves, tokens, cookies ou credenciais.

Resultado esperado e limite final

A Skill pode produzir uma análise curta e rastreável: o que o plano mostra, qual consulta é afetada, qual hipótese merece teste e qual mudança ficou sob aprovação. Ela não conhece sozinha a frequência real, a distribuição dos dados, o custo de escrita, o horário de pico ou a tolerância do serviço.

Use um ciclo progressivo. Primeiro, leitura de índices e plano. Depois, teste do índice em ambiente controlado ou com ferramenta apropriada. Em seguida, compare métricas antes e depois. Só então planeje implantação, monitoramento e rollback. Não transforme uma recomendação de IA em mudança direta de produção.

A documentação oficial de análise de planos mostra como identificar índice usado, documentos examinados e chaves examinadas. Essa evidência é mais útil que uma promessa genérica de ganho.

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, painel real, logotipo oficial, consulta executada, banco acessado nem prova de ganho de desempenho.

Fontes primárias

• Diretório oficial no commit auditado
• SKILL.md oficial fixado
• Princípios de índices da Skill
• Antipadrões oficiais da Skill
• Desempenho de consultas no manual MongoDB
• Exemplos oficiais do MongoDB MCP Server