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.

Puedes usar la configuración de consultas para añadir sugerencias de índices, definir filtros de rechazo de operación y establecer otros campos. La configuración se aplica a la forma del query en todo el clúster. El clúster conserva la configuración después del apagado.

Por ejemplo, la configuración del query permite usar un índice para todas las ejecuciones de una forma del query en un clúster.

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.

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

A partir de MongoDB 8.0, usa la configuración de query en lugar de filtros de índice. Los filtros de índice están obsoletos a partir de MongoDB 8.0.

La configuración de query tiene más funcionalidad que los filtros de índice. Además, los filtros de índice no son persistentes y no se pueden crear fácilmente filtros de índice para todos los nodos del clúster.

La configuración de la query tiene mayor prioridad que los "hints" de índice. MongoDB ignora las sugerencias de índice que se pasan como campos de comando cuando una configuración de query coincidente contiene sugerencias de índice. Las sugerencias de índice no afectan la forma del query. Para más información sobre sugerencias y configuraciones de query, consulte Sintaxis de la configuración de la query.

Nota

Para remover la configuración del query, utilice removeQuerySettings. Para obtener la configuración del query, utilice una etapa de $querySettings en una canalización de agregación.

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. Los ejemplos utilizan un índice para todas las ejecuciones de una forma del query ejecutada en el clúster.

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: { type: "pepperoni"} ,
      $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: { size: "medium" } },
         { $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