Cuando ejecutas una query de MongoDB Vector Search con el método explain, la query devuelve un documento BSON que contiene el plan del query y estadísticas de ejecución que describen cómo se ejecutó la query internamente.
Sintaxis
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>] } } } ])
nivel de verbosidad
El nivel de verbosidad controla el comportamiento de explain y la cantidad de información devuelta. El valor puede ser uno de los siguientes, en orden de menor a mayor nivel de verbosidad:
Información sobre el plan del query, incluyendo los campos | |
Información sobre el plan del query, incluidos los campos | |
queryPlanner (por defecto) | Información sobre el plan del query. No incluye los campos |
Explique los resultados
El método explain devuelve un documento BSON con los siguientes campos.
Opción | Tipo | Necesidad | Propósito |
|---|---|---|---|
| Documento | Opcional | Describe las estadísticas de ejecución para el recopilador. |
| Documento | Opcional | Contiene metadatos útiles. |
| Documento | Opcional | Describe las estadísticas de ejecución de la query. Esto no está presente en el nivel superior para |
| Documento | Opcional | Detalles relacionados con la recuperación de datos por documento después de la ejecución de la query. Esto no se devuelve para el |
| Documento | Opcional | Detalla el uso de recursos de la query cuando se ejecutó. Esto no se devuelve para el nivel de verbosidad |
| Arreglo de objetos | Opcional | Detalles de rastreo, tales como los siguientes, acerca de los vectores en los documentos especificados:
|
| Arreglo de objetos | Opcional | Detalles por segmento de Lucene de la ejecución de la query |
collectors
El collectors es un documento BSON con el siguiente campo:
Campo | Tipo | Necesidad | Propósito |
|---|---|---|---|
| Documento | Requerido | Estadísticas de todos los recopiladores de la query. Las estadísticas reportadas representan ya sea el valor máximo de todos los colectores utilizados en la query o la suma de la estadística de todos los subcolectores. Las estadísticas de tiempo se suman para reflejar el tiempo total empleado por todos los recopiladores en toda la query. Para aprender más, se puede consultar |
allCollectorStats
El allCollectorStats es un documento BSON que describe las estadísticas de los colectores en todos los colectores especificados en la query. Contiene las siguientes claves:
Campo | Descripción |
|---|---|
| Rastrea la duración y el número de resultados recogidos por el recolector. |
| Estadísticas que rastrean la duración total y el número de veces que se solicitó un |
| Estadísticas que rastrean la duración total y la cantidad de veces que un anotador fue configurado en el recolector. |
metadata
El metadata contiene metadatos útiles, como los siguientes:
Campo | Tipo | Necesidad | Propósito |
|---|---|---|---|
| String | Opcional | Versión actual de |
| String | Opcional | Etiqueta legible por humanos que identifica el |
| String | Opcional | Índice de búsqueda vectorial MongoDB utilizado en la query. |
| Documento | Opcional | Opciones de cursor otorgadas a |
| entero | Opcional | Número total de documentos en el índice, incluidos los documentos eliminados. |
query
La respuesta explain es un documento BSON con claves y valores que describen las estadísticas de ejecución de la query. El documento explain en el conjunto de resultados contiene los siguientes campos:
Campo | Tipo | Necesidad | Propósito |
|---|---|---|---|
| string | Opcional | Ruta al campo de incrustación consultado, solo si no es el raíz. |
| string | Requerido | Nombre del tipo de query de búsqueda vectorial. Consulta |
| Documento | Requerido | Información de la query de búsqueda vectorial. Consulta |
| Documento | Opcional |
|
args
La respuesta de explicación contiene información sobre cómo se ejecutó la query internamente. El campo args incluye los siguientes detalles:
Tipo de query
Un ejemplo de resumen estructurado para cada tipo de query
Opciones de consulta en el resumen estructurado
Las secciones siguientes describen los tipos de query y los campos de los resúmenes estructurados:
WrappedKnnQueryUna consulta contenedor utilizada para la búsqueda vectorial ANN que combina varias consultas. El resumen estructurado incluye detalles sobre las siguientes opciones:
CampoTipoNecesidadDescripciónqueryArreglo
Requerido
Arreglo de subconsultas utilizadas en la búsqueda vectorial, que suelen contener
KnnFloatVectorQueryyDocAndScoreQuery.
KnnFloatVectorQueryUn tipo de query específico para la búsqueda ANN en vectores de punto flotante. El resumen estructurado incluye detalles sobre las siguientes opciones:
CampoTipoNecesidadDescripciónfieldString
Requerido
La ruta de campo vectorial que se está buscando.
kentero
Requerido
Número de vecinos más cercanos para recuperar.
DocAndScoreQueryUn tipo de query que gestiona la coincidencia y puntuación de documentos. El resumen estructurado generalmente incluye estadísticas sobre la ejecución de la query.
ExactVectorSearchQueryUn tipo de query para búsquedas de vectores ENN. El resumen estructurado incluye detalles sobre las siguientes opciones:
CampoTipoNecesidadDescripciónfieldString
Requerido
La ruta de campo vectorial que se está buscando.
similarityFunctionString
Requerido
La función de similitud utilizada (
dotProduct,cosineoeuclidean).filterDocumento
Opcional
query previa que limita el alcance de la búsqueda vectorial.
BooleanQuerySi utiliza un prefiltro en su query de búsqueda vectorial, sus resultados de explicación incluyen el tipo
BooleanQuery. Para obtener más información sobre los campos de este tipo y otros tipos de query específicos de tu query de prefiltro, consulta los Tipos de Query en la Página de explicación de MongoDB Search.
stats
La respuesta explain para las moda de nivel de verbosidad de executionStats y allPlansExecution incluye un campo stats que contiene información sobre cuánto time dedica una query en las diversas stages of query de ejecución.
Desglose por tiempo
El desglose de temporización describe estadísticas de ejecución pertinentes a una áreas de query ejecución. Los siguientes campos muestran el desglose temporal:
Campo | Tipo | Descripción |
|---|---|---|
| Long | |
| Documento | Número de invocaciones de tareas incluidas en esta área. El valor es un mapa de nombres de tareas a su recuento de invocaciones. |
Áreas de Consulta
Las estadísticas están disponibles para las siguientes áreas de query:
Opción | Descripción | |||||||
|---|---|---|---|---|---|---|---|---|
| Estadísticas relacionadas con la ejecución de la query de búsqueda vectorial. Hay dos tareas cuyos recuentos de convocación se enumeran en esta área:
El tiempo dedicado en esta área está relacionado con la estructura de la query, y no se basa en el número de resultados que se recorren y se puntúan. Por ejemplo: | |||||||
| Estadísticas relacionadas con la iteración y la coincidencia de documentos de resultados. Esta estadística muestra el tiempo que requiere determinar qué documento es la siguiente coincidencia. El tiempo dedicado a comparar resultados puede variar significativamente dependiendo de la naturaleza de la query. En esta área se enumeran dos tareas cuyos recuentos de invocación son:
Por ejemplo: | |||||||
| Estadísticas relacionadas con la puntuación de los documentos en el conjunto de resultados. Hay dos tareas cuyos recuentos de invocación se enumeran en esta área:
Por ejemplo: |
resourceUsage
El documento resourceUsage muestra el recurso utilizado para ejecutar la query. Contiene los siguientes campos:
Campo | Tipo | Necesidad | Propósito |
|---|---|---|---|
| Long | Requerido | Número de fallos de página mayores, que ocurren cuando el sistema no puede encontrar los datos requeridos en la memoria, lo que resulta en la lectura desde el almacén de respaldo, como el disco, durante la ejecución de la query. |
| Long | Requerido | Número de fallos menores de página, que ocurren cuando los datos están en la caché de páginas, pero aún no se han mapeado a la tabla de páginas del proceso. |
| Long | Requerido | Cantidad de tiempo de CPU, en milisegundos, pasado en espacio de usuario. |
| Long | Requerido | Cantidad de tiempo de CPU, en milisegundos, utilizado en el espacio del sistema. |
| entero | Requerido | Número máximo de hilos que |
| entero | Requerido | Cantidad total de lotes que se solicitaron |
vectorTracing
El arreglo vectorTracing contiene una lista de objetos, uno por documento, que tiene la siguiente información sobre los vectores en el documento:
Campo | Tipo | Necesidad | Propósito |
|---|---|---|---|
| Booleano | Requerido | Indicador que especifica si el vector rastreado fue visitado durante la ejecución de la query. |
| String | Condicional | Razón para dejar caer el vector. Esto solo está presente si el vector fue visitado y descartado de los resultados. El valor puede ser:
|
| Double | Condicional | Puntuación asociada al vector. Esto está presente solo si se visitó el vector |
| entero | Requerido | Número de segmento de Lucene al que pertenece el vector. Para aprender más, consulte |
| Booleano | Condicional | Indicador que especifica si el vector es inalcanzable. Esto solo está presente si el vector es inalcanzable. |
luceneVectorSegmentStats
El luceneVectorSegmentStats arreglo de objetos contiene el desglose por segmento de Lucene de la ejecución de la query $vectorSearch. Cada segmento se identifica con un número e incluye los parámetros que describen los detalles de ejecución de la 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 | Necesidad | Propósito |
|---|---|---|---|
| String | Requerido | La estrategia de ejecución. El valor puede ser uno de los siguientes:
|
| Float | Condicional | Tiempo (en milisegundos) para la fase aproximada. Esto solo se devuelve para los tipos de ejecución |
| Float | Condicional | Tiempo (en milisegundos) para la fase Exacta. Esto solo se devuelve para los tipos de ejecución |
| entero | Opcional | El número de documentos que coinciden con el filtro de la query si se ha especificado un prefiltro en la query. |
| entero | Requerido | Número total de documentos en el segmento. |
Ejemplos
Los siguientes ejemplos utilizan el método explain en query de muestra ANN y ENN. Si se desea ejecutar los siguientes ejemplos en el propio entorno, primero se debe completar la Guía de inicio rápido de MongoDB búsqueda vectorial usando mongosh.
allPlansExecution
El siguiente ejemplo ejecuta el método explain en una ANN y ENN query de búsqueda vectorial para el plot_embedding_voyage_3_large campo con el allPlansExecution nivel de verbosidad moda.
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
El siguiente ejemplo ejecuta el método explain en una ANN y ENN query de búsqueda vectorial para el plot_embedding_voyage_3_large campo con el queryPlanner nivel de verbosidad moda.
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
El siguiente ejemplo ejecuta el método explain en una ANN y ENN query de búsqueda vectorial para el plot_embedding_voyage_3_large campo con el executionStats nivel de verbosidad moda.
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') ] } } } ])