Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Menu Docs
Página inicial do Docs
/ /
Administração
Página inicial do Docs
/
Desenvolvimento
/
Comandos de banco de dados
/
Administração
Página inicial do Docs
/
Desenvolvimento
/
Comandos de banco de dados
/
Administração

setQuerySettings (comando de banco de dados)

Definição

setQuerySettings

Novidades na versão 8.0.

setQuerySettings define as configurações de query utilizadas pelos find distinct aggregate comandos, e.

Você pode usar configurações de query para adicionar dicas de índice, definir filtros de rejeção de operação e definir outros campos para todas as execuções de uma determinada forma de query em um cluster. As configurações de query de um cluster persistem entre reinicializações.

O otimizador de query usa as configurações de query como uma entrada adicional durante o planejamento de query. As dicas de índice nas configurações de query restringem o conjunto de índices disponíveis para o planejador, mas não garantem que o planejador usará o índice. O planejador ainda pode selecionar uma verificação de collection como o plano vencedor para um determinado hash de forma de query .

As configurações de query de cluster têm precedência sobre as configurações de query ou dicas de índice passadas como um campo de comando . O MongoDB ignora dicas de índice em campos de comando se uma configuração de query correspondente já contiver dicas de índice.

As dicas de índice não afetam a forma de query.

Para obter mais informações sobre dicas e configurações de query, consulte Sintaxe das configurações de query.

Observação

Para remover as configurações de query,removeQuerySettings use. Para ver as configurações de consulta atuais, use um $querySettings estágio em um pipeline de agregação .

Configurações de query e filtros de índice

A partir do MongoDB,8.0os filtros de índice estão obsoletos. Em vez disso, use as configurações de query.

As configurações de query têm mais funcionalidades do que os filtros de índice. Os filtros de índice não são persistentes e não é possível criar facilmente filtros de índice para todos os nós do cluster.

Sintaxe

Você pode adicionar ou atualizar as configurações de query usando qualquer uma das duas especificações de sintaxe mostradas nesta seção.

Definir configurações de query passando uma query

Na seguinte sintaxe, você fornece:

  • Os mesmos campos que um comando find, distinct ou aggregate . Consulte as seções de sintaxe nas páginas dos comandos para os campos que você pode incluir em setQuerySettings.

  • Um campo $db para especificar o banco de dados de dados para as configurações da query.

  • Um documento settings com indexHints e outros 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>
   }
} )

Definir configurações de query passando um hash de forma de query

Você pode fornecer uma string de hash de forma de query existente em setQuerySettings e um documento settings atualizado com indexHints e outros 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>
   }
} )

Um hash de forma de query é uma string que identifica exclusivamente a forma de query. Um exemplo de hash de forma de query é "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C".

Para obter a string de hash da forma de query , faça qualquer um destes:

Se você definir as configurações de query usando uma string de hash, não terá o campo representativeQuery na saída do estágio de agregação $querySettings .

Dica

Em ambas as variações de sintaxe , você pode fornecer uma array de documentos do indexHints . Você pode omitir os colchetes da array se fornecer apenas um documento indexHints .

Campos de comando

O comando usa esses campos:

Campo
tipo de campo
necessidade
Descrição

setQuerySettings

documento ou string

Obrigatório

Você pode fornecer:

  • Os mesmos campos que os de um comando find, distinct ou aggregate e um campo $db com o banco de dados de dados associado ao comando original.

  • Uma string de hash de forma de query existente que identifica exclusivamente a forma de query. Um exemplo de hash de forma de query é "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`.

indexHints.ns

documento

Opcional

Namespace para dicas de índice. Obrigatório apenas quando dicas de índice opcionais são especificadas.

db

string

Obrigatório

Nome do banco de banco de dados para dicas de índice.

coll

string

Obrigatório

Nome da coleção para dicas de índice.

indexHints.allowedIndexes

array

Opcional

Array de índices para dicas de índice. Uma dica de índice pode ser uma destas:

  • Nome do Índice

  • padrão de chave de índice

  • $natural dica

Para obter mais detalhes, consulte Índices e hint().

queryFramework

string

Opcional

A string da estrutura de query pode ser definida como:

reject

booleano

Opcional

Se true:

  • Novas queries com a forma de query correspondente são rejeitadas e a resposta da query informa que a query é rejeitada.

  • As queries atualmente em andamento não serão rejeitadas.

O padrão é false.

Para habilitar uma forma de query, execute setQuerySettings novamente para a forma de query e defina reject como false. Se você definir reject como true e depois de volta para false usando setQuerySettings , então:

  • Se o documento settings não estiver vazio, o setQuerySettings ativará a forma de query.

  • Se o seu documento settings contiver apenas reject: false, então setQuerySettings retornará um erro. Em vez disso, utilize o comando removeQuerySettings para remover as configurações e então utilize setQuerySettings para adicionar configurações de query.

comment

Tipo de BSON

Opcional

Um comentário pode ser qualquer tipo de BSON válido. Por exemplo: string, objeto e assim por diante.

Você pode usar um comentário para fornecer informações adicionais sobre as configurações de query. Por exemplo, para adicionar uma string que indica por que você adicionou as configurações de query, use comment: "Index hint for orderDate_1 index to improve query performance".

Para atualizar um comentário, execute setQuerySettings novamente e use comment: { body: { msg: "Updated comment" } }.

Você não pode remover um comentário, mas pode defini-lo como uma string com um caractere de espaço. Você pode remover as configurações de query removeQuerySettings usando.

Os comentários aparecem na $querySettings saída do estágio do pipeline de agregação, na saída do comando explain() e nos registros de queries lentas.

Disponível a partir do MongoDB 8.1 (e 8.0.4).

Exemplos

Os exemplos a seguir criam uma coleção e adicionam configurações de consulta para comandos diferentes. Para todas as execuções de uma forma de query no cluster, os exemplos restringem o planejador de query ao uso do índice sugerido ou a uma verificação de collection.

1

Criar a coleção e os índices de exemplo

Executar:

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

Os índices têm os nomes padrão orderDate_1 e totalNumber_1.

2

Adicionar configurações de query para um comando de localização

O exemplo seguinte adiciona configurações de query para um comando find . O exemplo fornece campos em setQuerySettings para o comando find e inclui o índice orderDate_1 em 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) Verifique as configurações de query

Execute este comando explain :

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

A seguinte saída truncada mostra que as configurações de consulta estão definidas:

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) Executar a query

O exemplo a seguir executa a query:

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

O otimizador de query usa as configurações de query como uma entrada adicional durante o planejamento de query, o que afeta o plano selecionado para executar a query.

Saída da 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) Obtenha as configurações de query

O exemplo a seguir utiliza um estágio $querySettings em um pipeline de agregação para obter as configurações de consulta:

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

Saída truncada, que inclui o 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

Adicionar configurações de query para um comando distinto

O exemplo seguinte adiciona configurações de query para um 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

Adicionar configurações de query para um comando agregado

O exemplo a seguir adiciona configurações de query para um 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"
   }
} )

Saiba mais

Voltar

setDefaultRWConcern

Próximo

setUserWriteBlockMode

Receber um selo de habilidade

Domine "Otimização de Consultas" gratuitamente!

Saiba mais

Nesta página