setQuerySettings

Nesta página

Definição

Sintaxe
Campos de comando
Exemplos
Saiba mais

Definição

setQuerySettings

Novidades na versão 8.0.

Você pode usar as configurações de query para adicionar dicas de índice, definirfiltros de rejeção de operação e definir outros campos. As configurações se aplicam à forma de query em todo o cluster. O cluster mantém as configurações após o desligamento.

Por exemplo, as configurações de query permitem usar um índice para todas as execuções de uma forma de query em um cluster.

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.

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

A partir do MongoDB 8.0, use configurações de query em vez de filtros de índice. Os filtros de índice estão obsoletos a partir do MongoDB 8.0.

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

Observação

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

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

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

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:

Use um estágio $querySettings em um pipeline de agregação e examine o campo queryShapeHash .
Examine a saída do profiler de banco de dados de dados.
Visualize os registros de consulta lentos.

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 (documento, string, ...)

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:

classic para usar o mecanismo clássico.
sbe para usar o mecanismo de execução de query baseado em slot. Para obter detalhes, consulte Mecanismo de execução de query baseado em slot.

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.

Exemplos

Os exemplos a seguir criam uma coleção e adicionam configurações de consulta para comandos diferentes. Os exemplos usam um índice para todas as execuções de uma forma de query executada no cluster.

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.

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

(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'
         },
         ...
       }
     ...
     ]
   }
}

(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')
   }
]

(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'
      },
      representativeQuery: {
         find: 'pizzaOrders',
         filter: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } },
         sort: { totalNumber: 1 },
         '$db': 'test'
      }
   }
]

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: { type: "pepperoni"} ,
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "orderDate_1" ]
      },
      queryFramework: "classic"
   }
} )

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: { size: "medium" } },
         { $group: {
            _id: "$type",
            totalMediumPizzaOrdersGroupedByType: { $sum: "$totalNumber" }
         } }
      ],
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "totalNumber_1" ]
      },
      queryFramework: "classic"
   }
} )

Saiba mais

Voltar

setDefaultRWConcern

setUserWriteBlockMode