Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

Explique os resultados da Vector Search do MongoDB

Quando você executa uma query no MongoDB Vector Search com o método explain, a query retorna um documento BSON contendo o plano de query e estatísticas de execução que descrevem como a query foi executada internamente.

db.<myCollection>.explain("<verbosity>").aggregate([
{
"$vectorSearch": {
"exact": true | false,
"filter": {<filter-specification>},
"index": "<index-name>",
"limit": <number-of-results>,
"numCandidates": <number-of-candidates>,
"path": "<field-to-search>",
"queryVector": [<array-of-numbers>],
"explainOptions": {
"traceDocumentIds": [<array-of-document-IDs>]
}
}
}
])

O modo Verbosidade controla o comportamento do explain e a quantidade de informações retornadas. O valor pode ser um dos seguintes, em ordem decrescente de verbosidade:

Informações sobre o plano de query , incluindo os campos stats, que contêm estatísticas de execução da query. Inclui dados de execução parcial capturados durante a seleção do plano.

Informações sobre o plano de query, incluindo os campos stats, que contêm estatísticas de execução para a query.

queryPlanner (padrão)

Informações sobre o plano de query. Não inclui os campos stats, que contêm as estatísticas de execução da query.

O método explain retorna um documento BSON com os seguintes campos.

Opção
Tipo
necessidade
Propósito

collectors

documento

Opcional

Descreve as estatísticas de execução do coletor.

metadata

documento

Opcional

Contém metadados úteis.

query

documento

Opcional

Descreve as estatísticas de execução da query. Isso não está presente no nível superior para indexPartitionExplain.

resultMaterialization

documento

Opcional

Detalhes relacionados à recuperação de dados por documento após a execução da query. Isto não é devolvido para o modo de verbosidade queryPlanner .

resourceUsage

documento

Opcional

Detalha o uso de recursos da query quando ela foi executada. Isso não é retornado para o modo de detalhamento queryPlanner.

vectorTracing

Array de objetos

Opcional

Detalhes de rastreamento, como os seguintes, sobre vetores nos documentos especificados:

  • Se a pesquisa vetorial do MongoDB visitou o vetor durante a execução da query, se o vetor apareceu no conjunto de resultados da pesquisa vetorial do MongoDB e, se não, por que o vetor foi descartado.

  • Se o vetor é geralmente acessível porque alguns vetores podem não ser acessíveis devido à natureza probabilística dos Mundos Pequenos Hierárquicos Navegáveis.

luceneVectorSegmentStats

Array de objetos

Opcional

Detalhes do segmento por Lucene da execução da query $vectorSearch.

O collectors é um documento BSON com o seguinte campo:

Campo
Tipo
necessidade
Propósito

allCollectorStats

documento

Obrigatório

Statistics of all collectors of the query. Statistics reported represent either the maximum value across all collectors used in the query or a sum of the statistic across all the sub-collectors. The timing statistics are summed to reflect the total time spent across all collectors for the entire query. To learn more, see allCollectorStats.

O allCollectorStats é um documento BSON que descreve as estatísticas do coletor em todos os coletores especificados na query. Contém as seguintes chaves:

Campo
Descrição

collect

Acompanha a duração e o número de resultados coletados pelo coletor.

competitiveIterator

Estatísticas que rastreiam a duração total e o número de vezes que um competitiveIterator foi solicitado ao coletor.

setScorer

Estatísticas que monitoram a duração total e o número de vezes que um pontuador foi configurado no coletor.

O metadata contém metadados úteis, como os seguintes:

Campo
Tipo
necessidade
Propósito

mongotVersion

String

Opcional

Versão atual de mongot.

mongotHostName

String

Opcional

Etiqueta legível por humanos que identifica o host mongot.

indexName

String

Opcional

Índice de Vector Search do MongoDB usado na query.

cursorOptions

Documento

Opcional

Opções de cursor dadas a mongot.

totalLuceneDocs

Inteiro

Opcional

Número total de documentos no índice, incluindo documentos excluídos.

A resposta do explain é um documento BSON com chaves e valores descrevendo as estatísticas de execução da query. O documento explain no conjunto de resultados contém os seguintes campos:

Campo
Tipo
necessidade
Propósito

path

string

Opcional

Caminho para o campo de incorporação da consulta, somente se não for a raiz.

type

string

Obrigatório

Nome do tipo de query de pesquisa vetorial . Consulte query para mais informações.

args

documento

Obrigatório

Informações sobre a query de pesquisa vetorial. Consulte query para mais informações.

stats

documento

Opcional

stats for the query if explain ran with executionStats or allPlansExecution verbosity.

The explain response contains information how the query was executed internally. The args field includes the following details:

  • Tipo de query

  • Um exemplo de resumo estruturado para cada tipo de query

  • Opções de query no resumo estruturado

As seções a seguir descrevem os tipos de query e os campos nos resumos estruturados:

WrappedKnnQuery

Uma query wrapper usada para pesquisa vetorial de ANN que combina múltiplas queries. O resumo estruturado inclui detalhes sobre a seguinte opção:

Campo
Tipo
necessidade
Descrição

query

Array

Obrigatório

Array de subqueries usadas na pesquisa vetorial, normalmente contendo KnnFloatVectorQuery e DocAndScoreQuery.

KnnFloatVectorQuery

Um tipo de query específico para a pesquisa ANN em vetores flutuantes. O resumo estruturado inclui detalhes sobre as seguintes opções:

Campo
Tipo
necessidade
Descrição

field

String

Obrigatório

O caminho do campo vetorial que está sendo pesquisado.

k

Inteiro

Obrigatório

Número de vizinhos mais próximos a serem recuperados.

DocAndScoreQuery

Um tipo de query que lida com a correspondência e a pontuação de documento . O resumo estruturado normalmente inclui estatísticas sobre a execução da query.

ExactVectorSearchQuery

Um tipo de query para pesquisas de vetor ENN. O resumo estruturado inclui detalhes sobre as seguintes opções:

Campo
Tipo
necessidade
Descrição

field

String

Obrigatório

O caminho do campo vetorial que está sendo pesquisado.

similarityFunction

String

Obrigatório

A função de similaridade utilizada (dotProduct, cosine ou euclidean).

filter

Documento

Opcional

Query pré-filtro que limita o escopo da pesquisa vetorial.

BooleanQuery

If you use a pre-filter in your vector search query, your explain results include the BooleanQuery type. To learn more about the fields for this type and other query types specific to your pre-filter query, refer to the Query Types on the MongoDB Search Explain Page.

DefaultQuery

As queries que não são explicitamente definidas por outra query são serializadas usando a query padrão. O resumo estruturado inclui detalhes sobre a seguinte opção:

Campo
Tipo
necessidade
Descrição

queryType

String

Obrigatório

Tipo de query.

The explain response for executionStats and allPlansExecution verbosity modes includes a stats field that contains information on how much time a query spends in various stages of query execution.

O detalhamento do tempo descreve as estatísticas de execução pertinentes a áreas de execução da query. Os campos a seguir mostram o detalhamento do tempo:

Campo
Tipo
Descrição

millisElapsed

Long

Tempo aproximado de relógio de parede decorrido na execução de tarefas nessa área, incluindo o tempo que os filhos da consulta passaram nessa área. O valor é o número aproximado de milissegundos decorridos durante a execução de tarefas nessa área.

invocationCounts

Documento

Number of invocations of tasks included in this area. The value is a map of task names to their invocation count.

As estatísticas estão disponíveis para as seguintes áreas de query:

Opção
Descrição

context

Estatísticas relacionadas à execução da query de pesquisa vetorial . Há duas tarefas cujas contagens de invocação estão enumeradas nesta área:

  • createScorer: O Scorer itera sobre os documentos e gera uma pontuação para cada documento. As invocações de createScorer criam o objeto responsável pela pontuação. Observe que o tempo associado a esta tarefa não é o tempo gasto na pontuação real de documento. A contagem inclui o número de invocações de scorerSupplier.

  • createWeight: Weight armazena o estado associado a uma query e IndexSearcher. A contagem inclui o número de invocações de createWeight.

The time spent in this area is related to the structure of the query, and is not based on the number of results that are iterated through and scored.

Por exemplo:

"context" : {
"millisElapsed" : NumberDouble(4.934751),
"invocationCounts" : {
"createWeight" : NumberLong(1),
"createScorer" : NumberLong(10)
}
}

match

Estatísticas relacionadas à iteração e à correspondência de documentos de resultados. Essa estatística mostra o tempo necessário para determinar qual documento é a próxima correspondência. O tempo gasto na correspondência de resultados pode variar significativamente, dependendo da natureza da query. Há duas tarefas cujas contagens de invocação são enumeradas nesta área:

  • nextDoc: Solicitações para avançar para o próximo documento do conjunto de resultados. Isso envolve identificar e superar saltos ou outras tarefas necessárias para encontrar a próxima correspondência. A contagem inclui o número de invocações de nextDoc e advance.

  • refineRoughMatch: Executa uma correspondência mais completa. Algumas query são executadas em um processo de duas fases, onde um documento é primeiro "grosseiramente" correspondido e verificado com uma segunda fase mais completa somente após satisfazer a primeira correspondência aproximada. A tarefa refineRoughMatch é a segunda fase do processo de duas fases. A contagem inclui o número de invocações de refineRoughMatch.

Por exemplo:

"match" : {
"millisElapsed" : NumberDouble(4.901597),
"invocationCounts" : {
"nextDoc" : NumberLong(541),
"refineRoughMatch" : NumberLong(0)
}
}

score

Estatísticas relacionadas à pontuação de documentos no conjunto de resultados. Há duas tarefas cujas contagens de invocação são enumeradas nesta área:

  • score: Pontua cada documento no conjunto de resultados. A contagem inclui o número de invocações de score.

  • setMinCompetitiveScore: Ignora documentos cujo score seja menor que o valor fornecido. Indica que uma query pode ter conseguido reduzir o número de operações de pontuação realizadas ao ignorar documentos com pontuações abaixo de um limite não competitivo. A contagem inclui o número de invocações de setMinCompetitiveScore.

Por exemplo:

"score" : {
"millisElapsed" : NumberDouble(3.931312),
"invocationCounts" : {
"score" : NumberLong(536),
"setMinCompetitiveScore" : NumberLong(0)
}
}

O documento resourceUsage mostra o recurso utilizado para executar a query. Ele contém os seguintes campos:

Campo
Tipo
necessidade
Propósito

majorFaults

Long

Obrigatório

Número de falhas de página principais, que ocorrem quando o sistema não consegue encontrar os dados necessários na memória, resultando na leitura do armazenamento de apoio, como disco, durante a execução da query.

minorFaults

Long

Obrigatório

Número de falhas de página menores, que ocorrem quando os dados estão no cache de página, mas ainda não foram mapeados para a tabela de páginas do processo.

userTimeMs

Long

Obrigatório

Tempo da CPU, em milissegundos, gasto no espaço do usuário.

systemTimeMs

Long

Obrigatório

Tempo da CPU, em milissegundos, gasto no espaço do sistema.

maxReportingThreads

Inteiro

Obrigatório

Número máximo de threads que mongot utilizou durante a execução da query em todos os lotes. Para consultas de explicação não concorrentes, o valor é 1.

numBatches

Inteiro

Obrigatório

Número total de lotes que mongot foi solicitado ao processar a query.

A array vectorTracing contém uma lista de objetos, um por documento, que possui os seguintes detalhes sobre os vetores no documento:

Campo
Tipo
necessidade
Propósito

visited

Boolean

Obrigatório

Sinalizador que especifica se o vetor rastreado foi visitado durante a execução da query.

dropReason

String

Condicional

Motivo para descartar o vetor. Isto está presente somente se o vetor foi visitado e descartado dos resultados. O valor pode ser:

  • Merge

  • NonCompetitiveScore

  • Filter

  • Rescoring

vectorSearchScore

Double

Condicional

Pontuação associada ao vetor. Isto está presente apenas se o vetor foi visitado

luceneSegment

Inteiro

Obrigatório

Lucene segment number to which the vector belongs. To learn more, see luceneVectorSegmentStats.

unreachable

Boolean

Condicional

Sinalizador que especifica se o vetor é inacessível. Está presente apenas se o vetor não estiver acessível.

A array de objetos luceneVectorSegmentStats contém detalhamento por segmento Lucene da execução da query $vectorSearch. Cada segmento é identificado por um número e inclui os parâmetros que descrevem os detalhes de execução da query.

{
"0": {
"executionType": "Approximate",
"approximateTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 100
},
"1": {
"executionType": "Exact",
"exactTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 55
},
"2": {
"executionType": "ApproximateToExactFallback",
"approximateTimeMillis": 0.10825,
"exactTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 55
}
}
Campo
Tipo
necessidade
Propósito

executionType

String

Obrigatório

A estratégia de execução. O valor pode ser um dos seguintes:

  • Approximate

  • Exact

  • ApproximateToExactFallback

approximateStage

Float

Condicional

Tempo (em milissegundos) para a fase aproximada. Isso é retornado apenas para os tipos de execução Approximate e ApproximateFallbackToExact.

exactStage

Float

Condicional

Tempo (em milissegundos) para a fase Exata. Isso é retornado apenas para os tipos de execução Exact e ApproximateFallbackToExact.

filterMatchedDocsCount

Inteiro

Opcional

O número de documentos que corresponderam ao filtro de queries se você especificou um pré-filtro na query.

docCount

Inteiro

Obrigatório

Número total de documentos no segmento.

The following examples use the explain method on sample ANN and ENN queries. If you want to run the following examples in your own environment, you must first complete the MongoDB Vector Search Quick Start using mongosh.

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the allPlansExecution verbosity mode.

db.embedded_movies.explain("allPlansExecution").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the queryPlanner verbosity mode.

db.embedded_movies.explain("queryPlanner").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the executionStats verbosity mode.

db.embedded_movies.explain("executionStats").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])