/ /

Administração

Página inicial do Docs

/ /

Comandos de banco de dados

Administração

Página inicial do Docs

Desenvolvimento

Referência

Comandos de banco de dados

Administração

setQuerySettings (comando de banco de dados)

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.

As configurações de query têm precedência mais alta do que as dicas de índice. O MongoDB ignora as dicas de índice que você passa como campos de comando quando uma configuração de query correspondente contém 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, 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>,
      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:

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

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.

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

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",
      comment: "Index hint for orderDate_1 index to improve query performance"
   }
} )

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

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

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",
      comment: "Index hint for orderDate_1 index to improve query performance"
   }
} )

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",
      comment: "Index hint for totalNumber_1 index to improve query performance"
   }
} )

Saiba mais

Voltar

setDefaultRWConcern

setUserWriteBlockMode

Definição

Observação

Sintaxe

Definir configurações de query passando uma query

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

Dica

Campos de comando

Exemplos

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

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

(Opcional) Verifique as configurações de query

(Opcional) Executar a query

(Opcional) Obtenha as configurações de query

Adicionar configurações de query para um comando distinto

Adicionar configurações de query para um comando agregado

Saiba mais

Receber um selo de habilidade