Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

setQuerySettings (comando de base de datos)

setQuerySettings

Nuevo en la versión 8.0.

setQuerySettings define la configuración de query utilizada por los comandos find, distinct y aggregate.

Puedes utilizar la configuración de query para añadir sugerencias de índices, definir filtros de rechazo de operaciones y establecer otros campos para todas las ejecuciones de una determinada forma del query en un clúster. La configuración de query de un clúster persiste a través de los reinicios.

El optimizador del query utiliza la configuración del query como un input adicional durante la planificación del query. Las sugerencias de índices en la configuración de query restringen el conjunto de índices disponibles para el planificador, pero no garantizan que el planificador usará el índice. El planificador aún puede seleccionar un escaneo de colección como el plan ganador para un determinado hash de la forma del query.

Los ajustes de query de clúster tienen prioridad sobre los ajustes de query o las sugerencias de índice pasadas como campo de comando. MongoDB ignora las sugerencias de índice en los campos de comando si una configuración de query correspondiente ya contiene sugerencias de índice.

Las sugerencias de índices no afectan la forma del query.

Para obtener más información sobre las sugerencias y la configuración de query, vea Sintaxis de configuración de query.

Nota

Para remover la configuración de la query, use removeQuerySettings. Para ver la configuración actual de la query, usa una etapa $querySettings en una pipeline de agregación.

A partir de MongoDB 8.0, los filtros de índice están en desuso. En su lugar, utiliza la configuración de query.

Los ajustes de query tienen más funcionalidades que los filtros de índices. Los filtros de índice no son persistentes y es difícil crear filtros de índice para todos los nodos del clúster.

Este comando está disponible en implementaciones alojadas en los siguientes entornos:

  • MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Importante

Este comando no es compatible con los clústeres M0 y Flex. Para obtener más información, consulta Comandos no compatibles.

  • MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB

  • MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

No puedes ejecutar setQuerySettings en una instancia demongod independiente. setQuerySettings requiere un conjunto de réplicas o un clúster fragmentado. Para usar la configuración de consulta en un entorno de prueba, despliega un conjunto de réplicas. Para aprender cómo, consulta Desplegar un conjunto de réplicas autogestionado para pruebas y desarrollo.

Puede añadir o actualizar la configuración de query utilizando cualquiera de las dos especificaciones de sintaxis que se muestran en esta sección.

En la siguiente sintaxis, usted proporciona:

  • Los mismos campos que un comando find, distinct o aggregate. Consulta las secciones de sintaxis en las páginas de esos comandos para ver los campos que puedes incluir en setQuerySettings.

  • Un campo $db para especificar la base de datos para los ajustes de la query.

  • Un documento settings con indexHints y otros campos.

db.adminCommand( { setQuerySettings: { <fields>, // Provide fields for // find, distinct, or aggregate command $db: <string> // Provide a database name }, // Provide a settings document with indexHints and other fields settings: { indexHints: [ { ns: { db: <string>, coll: <string> }, allowedIndexes: <array> }, ... ], queryFramework: <string>, reject: <boolean>, comment: <BSON type>, queryKnobs: <document>, maxTimeMS: <non-negative integer> }} )

Puede proporcionar una cadena hash de forma del query existente en setQuerySettings y un documento actualizado settings con indexHints y otros campos:

db.adminCommand( { setQuerySettings: <string>, // Provide an existing query shape hash string // Provide a settings document with indexHints and other fields settings: { indexHints: [ { ns: { db: <string>, coll: <string> }, allowedIndexes: <array> }, ... ], queryFramework: <string>, reject: <boolean>, comment: <BSON type>, queryKnobs: <document>, maxTimeMS: <non-negative integer> }} )

Un hash de forma del query es un string que identifica de manera única la forma del query. Un ejemplo de forma del query hash es "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C".

En las versiones actuales compatibles, se espera que la misma forma del query produzca la misma encriptada de la forma del query en todos los nodos y tipos de implementación. Para aprender cómo se comporta la encriptada en los nodos, los tipos de implementación y los clústeres, consulte Estabilidad de la encriptada de la forma del query.

Para obtener la string hash de la forma del query, haz cualquiera de estos:

Si configuras los parámetros de query utilizando una string encriptada, el campo representativeQuery no está presente inicialmente en el resultado de la etapa de agregación $querySettings.

A partir de MongoDB 8.3, si la compatibilidad de características entre versiones es 8.3 o posterior, MongoDB rellena el campo representativeQuery para la configuración de query que establezca con una forma del query encriptada. Cuando MongoDB ejecuta un query que coincide con la forma del query, cronograma el relleno. El rellenado no requiere ninguna acción por su parte.

El rellenado se ejecuta de forma asincrónica con el máximo esfuerzo para limitar el impacto en el rendimiento de tus queries. No se garantiza que una configuración de query se rellene la primera vez que se ejecuta una query coincidente. Si un rellenado no se completa, MongoDB lo intenta de nuevo la próxima vez que se ejecuta una query coincidente.

Para albergar las additional representative queries, MongoDB 8.3 también aumenta la capacidad de almacenamiento para representative queries en configuraciones de query más allá del límite original de 16 MB del documento BSON.

Tip

En ambas variaciones de sintaxis, puede proporcionar un arreglo de indexHints documentos. Puede omitir los corchetes de arreglo[] si proporciona solo un documento indexHints.

El documento settings en el comando setQuerySettings toma los siguientes campos:

Campo
tipo de campo
Necesidad
Descripción

setQuerySettings

Documento o string

Requerido

Puedes proporcionar cualquiera de las siguientes opciones:

  • Los mismos campos que los de un comando find, distinct o aggregate y un campo $db con la base de datos asociada al comando original.

  • Una string hash de una forma del query existente que identifica de manera única la forma del query. Un ejemplo de hash de forma del query es "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`.

indexHints.ns

Documento

Opcional

namespace para sugerencias de índice. Solo se requiere cuando se especifican sugerencias de índices opcionales.

indexHints.ns.db

string

Condicional

Nombre de la base de datos para las sugerencias de índice. Requerido cuando especifica indexHints.ns.

indexHints.ns.coll

string

Condicional

Nombre de la colección para las sugerencias de índice. Requerido cuando especifica indexHints.ns.

indexHints.allowedIndexes

arreglo

Opcional

Arreglo de índices para pistas de índices. Una sugerencia de índice puede ser una de las siguientes:

  • Nombre del índice

  • patrón de clave de índice

  • $natural hint

Para más detalles, consulta Índices y hint().

queryFramework

string

Opcional

La estructura del query string puede configurarse en:

reject

booleano

Opcional

En caso de que true:

  • Se rechazan las nuevas queries con la forma del query coincidente y la respuesta del query indica que el query ha sido rechazada.

  • No se rechaza ninguna consulta que esté en curso en este momento.

El valor por defecto es false.

Para habilitar una forma del query, ejecute setQuerySettings nuevamente para la forma del query y configure reject a false. Si configuras reject en true y luego de nuevo en false usando setQuerySettings, entonces:

  • Si tu documento settings no está vacío, entonces setQuerySettings habilita la forma del query.

  • Si tu documento settings solo contiene reject: false, entonces setQuerySettings devuelve un error. En su lugar, utiliza el comando removeQuerySettings para remover la configuración y luego usa setQuerySettings para añadir la configuración de consulta.

comment

Tipo BSON

Opcional

Un comentario puede ser de cualquier tipo BSON válido. Por ejemplo: string, objeto, etc.

Puedes usar un comentario para proporcionar información adicional sobre la configuración de la query. Por ejemplo, para agregar una string que indique por qué agregaste la configuración de la query, utiliza comment: "Index hint for orderDate_1 index to improve query performance".

Para actualizar un comentario, ejecuta setQuerySettings de nuevo y usa comment: { body: { msg: "Updated comment" } }.

No puedes remover un comentario, pero puedes establecerlo como una cadena que contenga un carácter de espacio. Puedes remover la configuración de la query utilizando removeQuerySettings.

Los comentarios aparecen en la salida de la etapa de la canalización de agregación $querySettings, la salida del comando explain() y los registros de consultas lentas.

Nuevo en la versión 8.1: (y 8.0.4).

queryKnobs

Documento

Opcional

Un documento de { <knobName>: <value> } pares que anulan los parámetros internos del servidor solo para esta forma del query, en lugar de para toda la instancia con setParameter. Cada control mantiene el tipo, los límites y el valor por defecto de su parámetro de servidor subyacente.

A diferencia de los otros campos setQuerySettings, que reemplazan el valor completo cuando se establecen, queryKnobs se fusiona con los valores de perilla existentes. setQuerySettings cambia los controles que incluye en el documento queryKnobs y deja todos los demás controles sin cambios.

queryKnobs: {} resulta en una operación nula. Para remover una sola perilla sin afectar a las demás, establezca el valor de esa perilla en null.

Nuevo en la versión 9.0.

maxTimeMS

non-negative integer

Opcional

Establece un límite de tiempo en milisegundos para las ejecuciones de la forma del query. Utilice esta configuración para limitar un único comportamiento regresado o aumentar un tiempo de espera del cliente demasiado ajustado sin cambiar el código de la aplicación.

Si omite maxTimeMS de la configuración de la query, el tiempo de espera de la operación sigue la opción maxTimeMS de nivel de comando y el parámetro del clúster defaultMaxTimeMS. Establecer maxTimeMS en 0 borra la configuración de query maxTimeMS, y la operación vuelve a los valores por defecto del nivel de comando y del clúster.

Un valor maxTimeMS establecido con setQuerySettings tiene prioridad sobre un valor maxTimeMS proporcionado en el comando.

Nuevo en la versión 9.0.

Nuevo en la versión 9.0.

A partir de MongoDB 9.0, puede utilizar la configuración queryKnobs para anular los parámetros internos del servidor para una única forma del query en lugar de toda la instancia. Configure el campo queryKnobs para querys dirigidas para mitigar el impacto de una forma regresada sin cambiar el comportamiento de otras cargas de trabajo en la misma implementación.

Por ejemplo, puede anular el notablescan parámetro del servidor para una única forma del query en lugar de toda la instancia estableciendo queryKnobs en { noTableScan: true }.

Cada perilla mantiene el tipo, los límites y el valor por defecto de su parámetro de servidor subyacente, y setQuerySettings ejecuta la misma validación que setParameter. setQuerySettings rechaza los siguientes valores:

  • Parámetros desconocidos

  • Parámetros que no están marcados como configurables a través de la configuración de query

  • Tipos de BSON types incorrectos

  • Cadenas enum inválidas

  • Valores fuera de rango

  • Parámetros cuyo requisito mínimo de compatibilidad de características entre versiones supera la compatibilidad de características entre versiones del clúster

El valor efectivo de una perilla sigue esta precedencia, de mayor a menor:

  1. Valores por forma establecidos con queryKnobs

  2. Valor de toda la instancia establecido con setParameter

  3. Valor por defecto compilado

Los parámetros de query forman parte de la configuración de query encriptada, por lo que también forman parte de la clave de caché de plan. Si cambia un valor de parámetro, MongoDB produce una nueva clave de caché de plan, por lo que el planificador crea un plan nuevo en lugar de reutilizar un plan en caché obsoleto.

A diferencia de setParameter, que se aplica por proceso y puede variar entre nodos, MongoDB aplica los mismos valores queryKnobs en todo el clúster para la forma del query coincidente.

Importante

Cuando degrada la compatibilidad de características entre versiones de 9.0 a una versión anterior, una migración actualiza la configuración de query almacenada. La migración remueve cada perilla cuya compatibilidad de características entre versiones mínima supera la versión de destino y borra cualquier entrada de configuración que aún contiene solo valores por defecto. Volver a actualizar a 9.0 no realiza la restauración de los mandos eliminados. Debe volver a aplicarlos con setQuerySettings.

Los siguientes ejemplos crean una colección y añaden configuraciones de query para diferentes comandos. Para todas las ejecuciones de una forma del query en el clúster, los ejemplos restringen al planificador de query a usar únicamente el índice sugerido o un escaneo de colección.

1

Ejecuta:

// Create pizzaOrders collection db.pizzaOrders.insertMany( [ { _id: 0, type: "pepperoni", size: "small", price: 19, totalNumber: 10, orderDate: ISODate( "2023-03-13T08:14:30Z" ) }, { _id: 1, type: "pepperoni", size: "medium", price: 20, totalNumber: 20, orderDate: ISODate( "2023-03-13T09:13:24Z" ) }, { _id: 2, type: "pepperoni", size: "large", price: 21, totalNumber: 30, orderDate: ISODate( "2023-03-17T09:22:12Z" ) }, { _id: 3, type: "cheese", size: "small", price: 12, totalNumber: 15, orderDate: ISODate( "2023-03-13T11:21:39.736Z" ) }, { _id: 4, type: "cheese", size: "medium", price: 13, totalNumber: 50, orderDate: ISODate( "2024-01-12T21:23:13.331Z" ) }, { _id: 5, type: "cheese", size: "large", price: 14, totalNumber: 10, orderDate: ISODate( "2024-01-12T05:08:13Z" ) }, { _id: 6, type: "vegan", size: "small", price: 17, totalNumber: 10, orderDate: ISODate( "2023-01-13T05:08:13Z" ) }, { _id: 7, type: "vegan", size: "medium", price: 18, totalNumber: 10, orderDate: ISODate( "2023-01-13T05:10:13Z" ) }] ) // Create ascending index on orderDate field db.pizzaOrders.createIndex( { orderDate: 1 } ) // Create ascending index on totalNumber field db.pizzaOrders.createIndex( { totalNumber: 1 } )

Los índices tienen los nombres por defecto orderDate_1 y totalNumber_1.

2

El siguiente ejemplo agrega configuraciones de query para un comando find. El ejemplo proporciona campos en setQuerySettings para el comando find, e incluye el índice orderDate_1 en allowedIndexes.

db.adminCommand( { setQuerySettings: { find: "pizzaOrders", filter: { orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) } }, sort: { totalNumber: 1 }, $db: "test" }, settings: { indexHints: { ns: { db: "test", coll: "pizzaOrders" }, allowedIndexes: [ "orderDate_1" ] }, queryFramework: "classic", comment: "Index hint for orderDate_1 index to improve query performance" }} )
3

Ejecuta este comando explain:

db.pizzaOrders.explain().find( { orderDate: { $gt: ISODate("2023-01-20T00:00:00Z" ) } } ).sort( { totalNumber: 1 } )

La siguiente salida truncada muestra que la configuración de la query está establecida:

queryPlanner: { winningPlan: { stage: 'SINGLE_SHARD', shards: [ { explainVersion: '1', ... namespace: 'test.pizzaOrders', indexFilterSet: false, parsedQuery: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } }, querySettings: { indexHints: { ns: { db: 'test', coll: 'pizzaOrders' }, allowedIndexes: [ 'orderDate_1' ] }, queryFramework: 'classic', comment: 'Index hint for orderDate_1 index to improve query performance' }, ... } ... ] }}
4

El siguiente ejemplo ejecuta la query:

db.pizzaOrders.find( { orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) } } ).sort( { totalNumber: 1 })

El optimizador de query utiliza la configuración del query como entrada adicional durante la planificación del query, lo que afecta al plan seleccionado para ejecutar el query.

Salida de la query:

[ { _id: 0, type: 'pepperoni', size: 'small', price: 19, totalNumber: 10, orderDate: ISODate('2023-03-13T08:14:30.000Z') }, { _id: 5, type: 'cheese', size: 'large', price: 14, totalNumber: 10, orderDate: ISODate('2024-01-12T05:08:13.000Z') }, { _id: 3, type: 'cheese', size: 'small', price: 12, totalNumber: 15, orderDate: ISODate('2023-03-13T11:21:39.736Z') }, { _id: 1, type: 'pepperoni', size: 'medium', price: 20, totalNumber: 20, orderDate: ISODate('2023-03-13T09:13:24.000Z') }, { _id: 2, type: 'pepperoni', size: 'large', price: 21, totalNumber: 30, orderDate: ISODate('2023-03-17T09:22:12.000Z') }, { _id: 4, type: 'cheese', size: 'medium', price: 13, totalNumber: 50, orderDate: ISODate('2024-01-12T21:23:13.331Z') }]
5

El siguiente ejemplo utiliza una etapa $querySettings en un pipeline de agregación para obtener la configuración de la query:

db.aggregate( [ { $querySettings: {} }] )

Salida truncada, que incluye el campo queryShapeHash:

[ { queryShapeHash: 'AB8ECADEE8F0EB0F447A30744EB4813AE7E0BFEF523B0870CA10FCBC87F5D8F1', settings: { indexHints: [ { ns: { db: 'test', coll: 'pizzaOrders' }, allowedIndexes: [ 'orderDate_1' ] } ], queryFramework: 'classic', comment: 'Index hint for orderDate_1 index to improve query performance' }, representativeQuery: { find: 'pizzaOrders', filter: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } }, sort: { totalNumber: 1 }, '$db': 'test' } }]
6

El siguiente ejemplo agrega configuraciones de query para un comando distinct:

db.adminCommand( { setQuerySettings: { distinct: "pizzaOrders", key: "totalNumber", query: { totalNumber: 10, orderDate :{ '$gt': ISODate('2023-01-20T00:00:00.000Z') } } , $db: "test" }, settings: { indexHints: { ns: { db: "test", coll: "pizzaOrders" }, allowedIndexes: [ "orderDate_1" ] }, queryFramework: "classic", comment: "Index hint for orderDate_1 index to improve query performance" }} )
7

El siguiente ejemplo agrega configuraciones de query para un comando aggregate:

db.adminCommand( { setQuerySettings: { aggregate: "pizzaOrders", pipeline: [ { $match: { totalNumber: 10, orderDate :{ '$gt': ISODate('2023-01-20T00:00:00.000Z') } } }, { $group: { _id: "$type", totalMediumPizzaOrdersGroupedByType: { $sum: "$totalNumber" } } } ], $db: "test" }, settings: { indexHints: { ns: { db: "test", coll: "pizzaOrders" }, allowedIndexes: [ "totalNumber_1" ] }, queryFramework: "classic", comment: "Index hint for totalNumber_1 index to improve query performance" }} )
Obtén una insignia de habilidad

¡Domina "Query Optimization" gratis!

Más información

Califique esta página

Documentación