setQuerySettings (comando de banco de dados)

Configurações de query e filtros de índice

A partir do MongoDB 8.0, os 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.

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>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

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>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

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

Nas versões suportadas atualmente, espera-se que a mesma forma de query produza o mesmo hash de forma de query entre nós e tipos de implantação. Para aprender como o hash se comporta entre nós, tipos de implantação e clusters, consulte Estabilidade de hash de forma de query.

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 com hash, o campo representativeQuery é inicialmente ausente da saída do estágio de agregação $querySettings.

A partir do MongoDB 8.3, se a versão de compatibilidade do recurso for 8.3 ou posterior, o MongoDB preenche o campo representativeQuery para configurações de query que você define com um hash de forma de query. Quando o MongoDB executa uma query que corresponde à forma de query, ele agenda o backfill. O backfill não exige nenhuma ação de você.

O backfill é executado assincronamente na medida do possível para limitar o impacto no desempenho nas suas consultas. Uma configuração de query não tem garantia de ser preenchida retroativamente na primeira vez que uma query correspondente é executada. Se um backfill não for concluído, o MongoDB tenta novamente na próxima vez que uma query correspondente for executada.

Para armazenar as query representativas adicionais, o MongoDB 8.3 também aumenta a capacidade de armazenamento para query representativas nas configurações de query além do limite original de 16 MB de documentos BSON.

Controles de query

A partir do MongoDB 9.0, você pode usar a configuração queryKnobs para substituir parâmetros internos do servidor para uma única forma de query em vez de toda a instância. Defina o campo queryKnobs para query direcionadas para mitigar o impacto de uma forma regressiva sem alterar o comportamento de outras cargas de trabalho na mesma implantação.

Por exemplo, você pode substituir o parâmetro de servidor notablescan para uma única forma de query em vez de toda a instância, definindo queryKnobs como { noTableScan: true }.

Cada controle mantém o tipo, os limites e o padrão de seu parâmetro de servidor subjacente, e setQuerySettings executa a mesma validação que setParameter executa. setQuerySettings rejeita os seguintes valores:

• Knobs desconhecidos

• Botões que não estão marcados como configuráveis por meio de configurações de query

• BSON types incorretos

• Strings de enumeração inválidas

• Valores fora da faixa

• Parâmetros cujo requisito mínimo de versão de compatibilidade do recurso excede a versão de compatibilidade do recurso do cluster

O valor efetivo de um parâmetro segue esta precedência, da mais alta para a mais baixa:

1. Conjunto de valores por forma definido com queryKnobs

2. Valor de toda a instância definido com setParameter

3. Valor padrão compilado

Os knobs de query fazem parte das configurações de query com hash, portanto, também fazem parte da chave de cache de plano. Se você alterar um valor de knob, o MongoDB produz uma nova chave de cache de plano, para que o planejador crie um novo plano em vez de reutilizar um plano cache obsoleto.

Ao contrário do setParameter, que se aplica por processo e pode diferir entre nós, o MongoDB aplica os mesmos valores de queryKnobs em todo o cluster para a forma de query correspondente.