Ajustar o desempenho da consulta com o Assistente de Índice no Azure DocumentDB (versão prévia)

O Assistente de Índice é um assistente interno de ajuste de desempenho do Azure DocumentDB que ajuda a diagnosticar consultas lentas, entender o comportamento de execução da consulta e implementar estratégias de índice otimizadas. O Consultor de Índice analisa sua estrutura de consulta junto com estatísticas de coleta e de índice. Em seguida, o Assistente de Índice gera recomendações claras e controladas por dados com explicações legíveis que descrevem por que um índice específico ajudaria a melhorar o desempenho.

Benefícios do Assistente de Índice

Aqui estão alguns benefícios de usar o Assistente de Índice.

  • Identificar gargalos de desempenho e consultas ineficientes.
  • Receba recomendações de índice acionáveis priorizadas pelo efeito de desempenho.
  • Entenda por que um índice importa através de explicações claras e simples em inglês.
  • Aplique recomendações de índice instantaneamente dentro da extensão.
  • Compare o desempenho antes e depois automaticamente quando o índice for criado.

Casos de uso para Assistente de Índices

O Assistente de Índice dá suporte a vários padrões de consulta e cenários de otimização para ajudar a melhorar o desempenho do banco de dados.

Scenario Description
Igualdade/Consulta de Alcance Manipula filtros simples de igualdade ou intervalo (por exemplo, field = value ou field > value).
Filtro Composto/Consulta Coberta/Junção de Pesquisa Analisa consultas que envolvem várias condições de filtro ou junções que podem ser otimizadas com índices compostos ou cobertos para Localizar Consultas.
Índices compostos Sugere índices de vários campos (composição) para dar suporte a consultas complexas de localização/classificação
Somente classificação Identifica quando uma operação de classificação pode ser melhorada ou coberta por um índice.
Filtro + Ordenar/Index Pushdown Recomenda estruturas de índice que permitem que a filtragem e a classificação sejam tratadas com eficiência dentro da camada de índice, reduzindo as verificações de documentos.
Cobertura de índice existente Com suporte para consultas find; se um índice já existir, nenhum novo índice será sugerido.

Se o cenário de consulta estiver fora desses padrões, entre em contato com a equipe do Azure DocumentDB para obter assistência com seu caso de uso específico.

Prerequisites

  • Uma assinatura de Azure

  • Um cluster existente do Azure DocumentDB

Conectar-se ao cluster do Azure DocumentDB

Conecte-se ao cluster do Azure DocumentDB dentro da extensão do Visual Studio Code.

  1. Abra a extensão do DocumentDB para Visual Studio Code na Barra de Atividades.

  2. Selecione Adicionar Conexão para criar uma nova conexão de cluster.

  3. Escolha o método de autenticação e forneça os detalhes de conexão necessários.

  4. Teste a conexão para garantir que ela esteja funcionando corretamente.

  5. Expanda seu cluster para exibir os bancos de dados e coleções disponíveis.

Abrir uma consulta para análise

Inicie a análise de desempenho com o Assistente de Índice abrindo uma consulta na extensão do DocumentDB.

  1. Abra uma consulta Localizar, Agregar ou Contar na extensão.

  2. Vá para a guia Insights de Consulta.

  3. Execute sua consulta. O painel exibe os principais indicadores de desempenho, como tempo de execução, documentos retornados, chaves examinadas e documentos examinados. O Assistente de Índice coleta e analisa o plano de execução da consulta e as estatísticas do cluster conectado (Modo Padrão) ou de dados pré-carregados (Modo de Pré-carregamento). Um modelo de linguagem (GitHub Copilot) examina o plano e as estatísticas sanitizados para recomendar índices ideais.

    Importante

    Todos os valores de consulta literal (por exemplo, emails, números ou texto) são substituídos por espaços reservados <value> antes de serem enviados para análise.

    Aqui está um exemplo da sanitização:

    • Consulta não sanitizada que não é enviada

      {
  "filter": {
    "email": "john.doe@example.com",
    "age": { "$gt": 25 }
  }
}

    • Consulta sanitizada que é enviada

      {
  "filter": {
    "email": "<value>",
    "age": { "$gt": "<value>" }
  }
}

  4. Aplicar uma recomendação diretamente; a extensão cria o índice e executa novamente a consulta para atualizar as métricas de desempenho.

  5. Examine os resumos das Estatísticas de Consulta e do Plano de Execução .

    Captura de tela da seção de estatísticas de consulta com informações, incluindo o tempo de execução, o número de documentos retornados e as chaves/documentos examinados.

  6. Explore a lista Oportunidades de Otimização . Cada recomendação inclui uma explicação legível por humanos e uma definição de índice sugerida.

    Captura de tela das oportunidades de otimização com uma lista de recomendações para a consulta atual.

  7. Selecione Aplicar para criar o índice recomendado. A criação de índice é executada de forma assíncrona em segundo plano. Depois de concluído, o painel é atualizado automaticamente com os resultados atualizados. Após a criação do índice, o Assistente de Índice executa novamente as métricas de análise e atualizações para que você possa comparar melhorias de desempenho.

Limitações do Assistente de Índice

Aqui estão as limitações do recurso assistente de índice.

  • Disponibilidade regional: Atualmente, o Assistente de Índice está disponível apenas nas regiões dos Estados Unidos e do Canadá .
  • Gerenciamento de índice: O Assistente de Índice recomenda apenas a criação de novos índices; não recomenda descartar ou ocultar índices existentes no momento.
  • Cobertura de cenário: Somente os cenários com suporte listados anteriormente são otimizados nesta versão. Para outros tipos de consulta, entre em contato com a equipe do Azure DocumentDB ou confira as Melhores Práticas de Indexação.
  • Confidencialidade de dados: Trate os nomes do banco de dados e da coleção como metadados, mas ainda examine as políticas internas de classificação de dados.

Práticas recomendadas ao usar o Assistente de Índice

Aqui estão as práticas recomendadas para usar o recurso assistente de índice.

  • Siga as políticas de governança de dados da sua organização ao exportar ou compartilhar estatísticas.
  • Examine as recomendações de índice antes de aplicá-las para garantir que elas se alinhem com seus requisitos de carga de trabalho e custo.
  • Evite remover índices manualmente sem examinar dependências ou consultar a equipe do Azure DocumentDB.
  • Se os padrões de consulta não tiverem suporte, confira as Práticas Recomendadas de Indexação para obter orientação e suporte.

Considerações para o Assistente de Índice

O Assistente de Índice foi criado para ajudá-lo a otimizar as consultas, protegendo a privacidade dos dados em todas as etapas.

Esta lista mostra os dados coletados pela extensão:

  • Planos de execução de consulta – informações estruturais e métricas de desempenho.
  • Estatísticas de coleta – contagem de documentos, dados e tamanhos de índice e contagens de índice.
  • Detalhes do índice – nomes de índice, padrões de chave e métricas de uso.
  • Metadados de cluster – informações limitadas, como o status de hospedagem do Azure e o tipo de API.

Conformidade e proteção de dados

Para garantir a conformidade e a proteção de dados, o sistema implementa as seguintes proteções antes de enviar qualquer informação para análise:

  • Substituindo todos os valores literais em consultas e planos de execução por <value>.
  • Retenção de nomes de campo e operadores de consulta (como email, $gt, $in) para preservar o contexto.
  • Planos de execução totalmente higienizados para garantir que nenhum dado confidencial ou pessoal permaneça.
  • Manter métricas de desempenho (como nReturned ou executionTimeMillis) porque elas não contêm valores literais de seus dados.
  • Transmitir apenas a estrutura, as estatísticas e os metadados higienizados necessários para análise— nunca exemplo de documentos ou valores brutos.
  • Submetendo qualquer recurso futuro que exija dados não autorizados à revisão completa de privacidade e conformidade da Microsoft.

O Assistente de Índice analisa apenas as características de desempenho e estrutura de consulta, nunca seus dados reais.

Conteúdo relacionado

  • Last updated on