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.
Dica
Sintaxe
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>] } } } ])
Detalhamento
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 | |
Informações sobre o plano de query, incluindo os campos | |
queryPlanner (padrão) | Informações sobre o plano de query. Não inclui os campos |
Explicação de resultados
O método explain retorna um documento BSON com os seguintes campos.
Opção | Tipo | necessidade | Propósito |
|---|---|---|---|
| documento | Opcional | Descreve as estatísticas de execução do coletor. |
| documento | Opcional | Contém metadados úteis. |
| documento | Opcional | Descreve as estatísticas de execução da query. Isso não está presente no nível superior para |
| 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 |
| documento | Opcional | Detalha o uso de recursos da query quando ela foi executada. Isso não é retornado para o modo de detalhamento |
| Array de objetos | Opcional | Detalhes de rastreamento, como os seguintes, sobre vetores nos documentos especificados:
|
| Array de objetos | Opcional | Detalhes do segmento por Lucene da execução da query |
collectors
O collectors é um documento BSON com o seguinte campo:
Campo | Tipo | necessidade | Propósito |
|---|---|---|---|
| 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 |
|---|---|
| Acompanha a duração e o número de resultados coletados pelo coletor. |
| Estatísticas que rastreiam a duração total e o número de vezes que um |
| Estatísticas que monitoram a duração total e o número de vezes que um pontuador foi configurado no coletor. |
metadata
O metadata contém metadados úteis, como os seguintes:
Campo | Tipo | necessidade | Propósito |
|---|---|---|---|
| String | Opcional | Versão atual de |
| String | Opcional | Etiqueta legível por humanos que identifica o host |
| String | Opcional | Índice de Vector Search do MongoDB usado na query. |
| Documento | Opcional | Opções de cursor dadas a |
| Inteiro | Opcional | Número total de documentos no índice, incluindo documentos excluídos. |
query
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 |
|---|---|---|---|
| string | Opcional | Caminho para o campo de incorporação da consulta, somente se não for a raiz. |
| string | Obrigatório | Nome do tipo de query de pesquisa vetorial . Consulte |
| documento | Obrigatório | Informações sobre a query de pesquisa vetorial. Consulte |
| documento | Opcional |
|
args
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:
WrappedKnnQueryUma query wrapper usada para pesquisa vetorial de ANN que combina múltiplas queries. O resumo estruturado inclui detalhes sobre a seguinte opção:
CampoTiponecessidadeDescriçãoqueryArray
Obrigatório
Array de subqueries usadas na pesquisa vetorial, normalmente contendo
KnnFloatVectorQueryeDocAndScoreQuery.
KnnFloatVectorQueryUm tipo de query específico para a pesquisa ANN em vetores flutuantes. O resumo estruturado inclui detalhes sobre as seguintes opções:
CampoTiponecessidadeDescriçãofieldString
Obrigatório
O caminho do campo vetorial que está sendo pesquisado.
kInteiro
Obrigatório
Número de vizinhos mais próximos a serem recuperados.
DocAndScoreQueryUm 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.
ExactVectorSearchQueryUm tipo de query para pesquisas de vetor ENN. O resumo estruturado inclui detalhes sobre as seguintes opções:
CampoTiponecessidadeDescriçãofieldString
Obrigatório
O caminho do campo vetorial que está sendo pesquisado.
similarityFunctionString
Obrigatório
A função de similaridade utilizada (
dotProduct,cosineoueuclidean).filterDocumento
Opcional
Query pré-filtro que limita o escopo da pesquisa vetorial.
BooleanQueryIf you use a pre-filter in your vector search query, your explain results include the
BooleanQuerytype. 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.
stats
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.
Detalhamento do tempo
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 |
|---|---|---|
| Long | |
| Documento | Number of invocations of tasks included in this area. The value is a map of task names to their invocation count. |
Áreas de query
As estatísticas estão disponíveis para as seguintes áreas de query:
Opção | Descrição | |||||||
|---|---|---|---|---|---|---|---|---|
| Estatísticas relacionadas à execução da query de pesquisa vetorial . Há duas tarefas cujas contagens de invocação estão enumeradas nesta área:
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: | |||||||
| 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:
Por exemplo: | |||||||
| Estatísticas relacionadas à pontuação de documentos no conjunto de resultados. Há duas tarefas cujas contagens de invocação são enumeradas nesta área:
Por exemplo: |
resourceUsage
O documento resourceUsage mostra o recurso utilizado para executar a query. Ele contém os seguintes campos:
Campo | Tipo | necessidade | Propósito |
|---|---|---|---|
| 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. |
| 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. |
| Long | Obrigatório | Tempo da CPU, em milissegundos, gasto no espaço do usuário. |
| Long | Obrigatório | Tempo da CPU, em milissegundos, gasto no espaço do sistema. |
| Inteiro | Obrigatório | Número máximo de threads que |
| Inteiro | Obrigatório | Número total de lotes que |
vectorTracing
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 |
|---|---|---|---|
| Boolean | Obrigatório | Sinalizador que especifica se o vetor rastreado foi visitado durante a execução da query. |
| String | Condicional | Motivo para descartar o vetor. Isto está presente somente se o vetor foi visitado e descartado dos resultados. O valor pode ser:
|
| Double | Condicional | Pontuação associada ao vetor. Isto está presente apenas se o vetor foi visitado |
| Inteiro | Obrigatório | Lucene segment number to which the vector belongs. To learn more, see |
| Boolean | Condicional | Sinalizador que especifica se o vetor é inacessível. Está presente apenas se o vetor não estiver acessível. |
luceneVectorSegmentStats
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 |
|---|---|---|---|
| String | Obrigatório | A estratégia de execução. O valor pode ser um dos seguintes:
|
| Float | Condicional | Tempo (em milissegundos) para a fase aproximada. Isso é retornado apenas para os tipos de execução |
| Float | Condicional | Tempo (em milissegundos) para a fase Exata. Isso é retornado apenas para os tipos de execução |
| Inteiro | Opcional | O número de documentos que corresponderam ao filtro de queries se você especificou um pré-filtro na query. |
| Inteiro | Obrigatório | Número total de documentos no segmento. |
Exemplos
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.
allPlansExecution
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 } } ])
db.embedded_movies.explain("allPlansExecution").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
queryPlanner
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 } } ])
db.embedded_movies.explain("queryPlanner").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
executionStats
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 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10, "explainOptions": { "traceDocumentIds": [ ObjectId('573a13d8f29313caabda6557'), ObjectId('573a1398f29313caabce98d9'), ObjectId('573a1391f29313caabcd8319'), ObjectId('573a1398f29313caabceb500'), ObjectId('573a1397f29313caabce780e') ] } } } ])