AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。
Docs Menu
Docs Home
/
開発
/
データベース コマンド
Docs Home
/
開発
/
データベース コマンド
Docs Home
/
開発
/
データベース コマンド

setQuerySettings（データベースコマンド）

定義

setQuerySettings

バージョン8.0の新機能。

setQuerySettings は、 find 、 distinct 、およびaggregateコマンドで使用されるクエリ設定を定義します。

クエリ設定を使用して、操作拒否フィルターの定義、インデックスヒントの追加、およびクラスターでの特定のクエリシェイプのすべての実行に対する他のフィールドの設定ができます。クラスターのクエリ設定は再起動後も保持されます。

The クエリオプティマイザ uses クエリ settings as an additional input during クエリ planning.クエリ設定 のインデックス ヒントは、プランナーで使用できるインデックスのセットを制限しますが、プランナーがインデックスを使用することを保証するものではありません。プランナーは、特定のクエリシェイプハッシュの最適なプランとしてコレクションスキャンを選択することもできます。

クラスタークエリ設定は、 コマンドフィールドとして渡されるクエリ設定やインデックスヒントよりも優先されます。MongoDB は、一致するクエリ設定にすでにインデックスヒントが含まれている場合、コマンド フィールド内のインデックスヒントを無視します。

インデックスのヒントはクエリシェイプには影響しません。

For more information about hints and query settings, see Query Settings Syntax.

注意

クエリ設定を削除するには、removeQuerySettings を使用します。現在のクエリ設定を確認するには、集計パイプラインの $querySettings ステージを使用します。

クエリ設定とインデックス フィルター

MongoDB 8.0 以降、インデックスフィルターは非推奨です。代わりにクエリ設定を使用してください。

クエリ設定は、インデックスフィルターよりも多くの機能を持ちます。インデックス フィルターは永続的ではなく、すべてのクラスター ノードのインデックスフィルターを簡単に作成することはできません。

互換性

このコマンドは、次の環境でホストされている配置で使用できます。

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

重要

This command is not supported in M0 and Flex clusters. For more information, see Unsupported Commands.

  • MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

  • MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

このセクションに示されている 2 つの構文仕様のいずれかを使用して、クエリ設定を追加または更新できます。

クエリを渡してクエリ設定を設定する

次の構文で、次の値を指定します。

  • find 、 distinct 、またはaggregateコマンドと同じフィールド。 setQuerySettingsに含めることができるフィールドのコマンドについては、 ページの構文セクションを参照してください。

  • クエリ設定のデータベースを指定する$dbフィールド。

  • indexHintsおよびその他のフィールドを持つsettingsドキュメント。

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

クエリシェイプハッシュを渡してクエリ設定を設定する

setQuerySettings には既存のクエリシェイプ ハッシュstringを指定し、indexHints およびその他のフィールドを使用して更新された settings ドキュメントを指定できます。

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

クエリシェイプ ハッシュは、クエリシェイプを一意に識別する string です。 クエリシェイプハッシュの例は"F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"です。

現在サポートされているバージョンでは、同じクエリシェイプは、ノードや配置タイプ全体で同じクエリシェイプハッシュを生成することが期待されています。ハッシュがノード、配置タイプ、クラスター全体でどのように動作するかを学ぶには、「クエリシェイプハッシュの安定性」を参照してください。

クエリシェイプ ハッシュstringを取得するには、次のいずれかを実行します。

ハッシュされた string を使用してクエリ設定を行った場合、representativeQuery フィールドは初期状態では $querySettings 集計ステージの出力に含まれていません。

MongoDB 8.3 以降、機能の互換性バージョン が 8.3 以降の場合、MongoDB は、クエリシェイプのハッシュを使用して設定したクエリ設定に対して、representativeQuery フィールドをバックフィルします。MongoDB がクエリシェイプに一致するクエリを実行するとき、バックフィルをスケジュールします。バックフィルにはあなたからのアクションは不要です。

バックフィルは、クエリのパフォーマンスへの影響を抑えるために、ベストエフォート方式で非同期に実行されます。クエリ設定は、一致するクエリが初めて実行されるときにバックフィルされることは保証されません。バックフィルが完了しない場合、MongoDB は一致するクエリが次回実行されると、それを再度試行します。

追加の代表クエリを保持するため、MongoDB 8.3 は、クエリ設定における代表クエリのストレージキャパシティーも増加し、元の 16 MB BSON ドキュメント制限を超えます。

Tip

どちらの構文バリエーションでも、 indexHintsドキュメントの配列を提供できます。 indexHintsドキュメントを 1 つだけ提供する場合は、配列括弧を省略できます。

コマンドフィールド

setQuerySettings コマンドの settings ドキュメントは、次のフィールドがあります。

フィールド
フィールド型
必要性
説明

setQuerySettings

ドキュメントまたは文字列

必須

次のいずれかを提供できます。

  • find 、 distinct 、またはaggregateコマンドと同じフィールド、および元のコマンドに関連付けられているデータベースを持つ$dbフィールドと同じフィールド。

  • クエリシェイプを一意に識別する既存のクエリシェイプ ハッシュstring 。 クエリシェイプハッシュの例は"F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`です。

indexHints.ns

ドキュメント

任意

インデックス ヒントの名前空間。 オプションのインデックス ヒントが指定されている場合にのみ必要です。

indexHints.ns.db

string

条件付き

インデックスのヒントのデータベース名。indexHints.ns を指定する場合は必須です。

indexHints.ns.coll

string

条件付き

インデックスヒントのコレクション名。indexHints.ns を指定する場合に必須です。

indexHints.allowedIndexes

配列

任意

インデックス ヒント用のインデックスの配列。 インデックスのヒントは、次のいずれかになります。

  • インデックス名

  • インデックスキーのパターン

  • $natural hint

詳細については、「インデックスとhint() 」を参照してください。

queryFramework

string

任意

クエリフレームワークstringは次のように設定できます。

reject

ブール値

任意

true場合:

  • 一致するクエリシェイプを持つ新しいクエリは拒否され、クエリ応答にクエリが拒否されたことが示されます。

  • 現在進行中のクエリは拒否されません。

デフォルトは、false に設定されています。

クエリシェイプを有効にするには、クエリシェイプに対してsetQuerySettingsを再度実行し、 rejectをfalseに設定します。 rejectをtrueに設定し、その後setQuerySettingsを使用してfalseに戻すと、次のようになります。

  • settingsドキュメントが空でない場合、 setQuerySettingsはクエリシェイプを有効にします。

  • If your settings document only contains reject: false, then setQuerySettings returns an error. 代わりに、 removeQuerySettingsコマンドを使用して設定を削除し、 setQuerySettingsを使用してクエリ設定を追加します。

comment

BSON Type

任意

コメントには有効なBSONタイプ であれば何でもかまいません。例: string、 オブジェクトなど。

コメントを使用して、クエリ設定に関する追加情報を提供できます。 例、クエリ設定を追加した理由を示す文字列を追加するには、comment: "Index hint for orderDate_1 index to improve query performance" を使用します。

コメントを更新するには、setQuerySettings を再度実行し、comment: { body: { msg: "Updated comment" } } を使用します。

コメントを削除することはできませんが、スペース文字を含む string に設定できます。 removeQuerySettingsを使用してクエリ設定を削除できます。

コメントは、$querySettings 集計パイプラインステージの出力、 explain() コマンドの出力 、 低速クエリ ログ に表示されます。

バージョン 8.1 で追加。（および 8.0.4）。

queryKnobs

ドキュメント

任意

setParameterでインスタンス全体に適用するのではなく、このクエリシェイプに対してのみ内部サーバーパラメータをオーバーライドする{ <knobName>: <value> }ペアのドキュメント。各ノブは、基礎のサーバーパラメータの型、境界、デフォルトを保持します。

他の setQuerySettings フィールドは設定時に値全体を置き換えますが、queryKnobs は既存のノブ値とマージされます。setQuerySettings は queryKnobs ドキュメントに含まれるノブを変更し、他のすべてのノブは変更しません。

queryKnobs: {} は、no-op（何もしない）になります。他のノブに影響を与えずに単一のノブを除くには、そのノブの値をnullに設定します。

バージョン9.0の新機能。

maxTimeMS

non-negative integer

任意

クエリシェイプの実行時間制限をミリ秒単位で設定します。この設定を使用して、アプリケーションコードを変更することなく、単一の回帰シェイプに上限を設けたり、過度に厳しいクライアントタイムアウトを解除したりできます。

クエリ設定から maxTimeMS を省略した場合、操作のタイムアウトはコマンドレベルの maxTimeMS オプションと defaultMaxTimeMS クラスターパラメーターに従います。maxTimeMS を 0 に設定すると、maxTimeMS クエリ設定がクリアされ、操作はコマンドレベルおよびクラスターのデフォルト値にフォールバックします。

setQuerySettings で設定された maxTimeMS の値は、コマンドで提供された maxTimeMS の値より優先されます。

バージョン9.0の新機能。

クエリ パラメータ

バージョン9.0の新機能。

MongoDB 9.0 以降、インスタンス全体ではなく、1 つの クエリシェイプ に対して、queryKnobs 設定を使用して内部サーバーパラメータを上書きすることができます。ターゲットクエリに対して queryKnobs フィールドを設定し、同じ配置上の他のワークロードの動作を変更せずに、1 つの劣化したシェイプの影響を軽減します。

例として、queryKnobs を { noTableScan: true } に設定することで、インスタンス全体ではなく単一のクエリシェイプに対して notablescan サーバーパラメータをオーバーライドできます。

各ノブは、基礎のサーバーパラメータの型、境界、およびデフォルトを維持します。また、setQuerySettings は setParameter が実行するのと同じ検証を実行します。setQuerySettingsは以下の値を拒否します。

  • 不明なノブ

  • クエリ設定から設定可能とマークされていないノブ

  • 誤ったBSON types

  • 無効な列挙文字列

  • 範囲外の値

  • 最低機能の互換性バージョン要件がクラスターの機能の互換性バージョンを超えるパラメータ

ノブの有効値は、優先順位が高い順に次のようになります。

  1. 形状ごとの値の設定方法 queryKnobs

  2. インスタンス全体で設定された値。 setParameter

  3. コンパイル時に組み込まれたデフォルト値

クエリノブはハッシュされたクエリ設定の一部であるため、プランキャッシュキーの一部でもあります。ノブの値を変更すると、MongoDBは新しいプランキャッシュキーを生成するため、プランナーは古いキャッシュされたプランを再利用するのではなく、新しいプランを作成します。

プロセスごとに適用され、ノード間で異なる可能性があるsetParameterとは異なり、MongoDBは一致するクエリシェイプに対してクラスター全体で同じqueryKnobs値を適用します。

重要

機能の互換性バージョンを9.0から以前のバージョンにダウングレードすると、移行によって保存 (する)クエリ設定が更新されます。移行では、最小機能の互換性バージョンがターゲットバージョンを超えるすべてのノブが除かれ、デフォルト値のみが含まれる設定エントリが削除されます。9.0に再アップグレードしても、削除されたノブは復元されません。setQuerySettingsを使用して再適用する必要があります。

例

次の例では、コレクションを作成し、さまざまなコマンドのクエリ設定を追加します。クラスターでのクエリシェイプのすべての実行において、クエリ プランナーはヒント指定したインデックスまたはコレクションスキャンのいずれかを使用するように制限されます。

1

サンプル コレクションとインデックスを作成する

実行: 

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

インデックスのデフォルト名はorderDate_1とtotalNumber_1です。

2

find コマンドのクエリ設定を追加する

次の例では、 findコマンドのクエリ設定を追加します。 この例では、 findコマンドのsetQuerySettingsにフィールドが含まれており、 allowedIndexesにorderDate_1インデックスが含まれています。

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

（オプション）クエリ設定を確認します

このexplainコマンドを実行します。

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

次の切り捨てられた出力は、クエリ設定が設定されていることを示しています。

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

（任意）クエリを実行する

次の例では、 クエリを実行します。

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

クエリオプティマイザは、クエリ設定中にクエリ設定を追加入力として使用し、クエリを実行するために選択されたプランに影響します。

クエリ出力は次のようになります。

[
   {
      _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

（任意）クエリ設定を取得する

次の例では、集計パイプラインの$querySettingsステージを使用してクエリ設定を取得します。

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

切り捨てられた出力（ 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

個別のコマンドのクエリ設定を追加する

次の例では、 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

集計コマンドのクエリ設定を追加しました

次の例では、 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"
   }
} )

詳細

戻る
setDefaultRWConcern
次へ
setUserWriteBlockMode
ルール バッジを取得する

「クエリの最適化」を無料でマスターしましょう！

詳細
このページを評価

項目一覧