Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Docs Menu
Docs Home
/ /
Administración
Docs Home
/
Desarrollo
/
Comandos de base de datos
/
Administración
Docs Home
/
Desarrollo
/
Comandos de base de datos
/
Administración

setQuerySettings (comando de base de datos)

Definición

setQuerySettings

Nuevo en la versión 8.0.

setQuerySettings define la configuración de query utilizada por el 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 sugerencias y configuraciones de query, consulta Sintaxis de la configuración de la 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.

Query Settings and filtros de índices

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.

Sintaxis

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.

Configurar los ajustes de query pasando una query

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>
   }
} )

Establecer la configuración del query pasando un hash de forma del query

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>
   }
} )

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".

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

Si configuras los parámetros de query utilizando una string hash, entonces no tendrás el campo representativeQuery en el resultado de la etapa de agregación $querySettings.

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.

Campos de comandos

El comando acepta estos 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.

db

string

Requerido

Nombre de la base de datos para sugerencias de índices.

coll

string

Requerido

Nombre de la colección para sugerencias de índices.

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.

Disponible a partir de MongoDB 8.1 (y 8.0.4).

Ejemplos

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

Cree la colección de ejemplo y los índices

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

Agregar ajustes de query para un comando de búsqueda

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

(Opcional) Verifica la configuración del query

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

(Opcional) Ejecuta la consulta

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

(Opcional) Obtener la configuración de query

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

Agregar configuraciones de query para un comando distinto

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

Agregar configuraciones de query para un comando de operación de conjunto

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 más información

Volver

setDefaultRWConcern

Next

setUserWriteBlockMode

Obtén una insignia de habilidad

¡Domina "Query Optimization" gratis!

Más información

En esta página