setQuerySettings
定義
バージョン8.0の新機能。
クエリ設定を使用して、インデックスのヒントを追加したり、 操作拒否フィルターを定義したり、他のフィールドを設定したりできます。 設定はクラスター全体のクエリシェイプに適用されます。 クラスターはシャットダウン後も設定を保持します。
たとえば、クエリ設定では、クラスター内のクエリシェイプのすべての実行にインデックスを使用できます。
クエリオプティマイザは、クエリ設定中にクエリ設定を追加入力として使用し、クエリを実行するために選択されたプランに影響します。
setQuerySettings は、 find 、 distinct 、およびaggregateコマンドで使用されるクエリ設定を定義します。
MongoDB 8.0以降では、インデックス フィルターの代わりに クエリ設定 を使用します。 インデックス フィルターは MongoDB 8.0以降非推奨です。
クエリ設定は、インデックス フィルターよりも多くの機能を持ちます。 また、インデックス フィルターは永続的ではなく、すべてのクラスター ノードに対してインデックス フィルターを簡単に作成することはできません。
注意
クエリ設定を削除するには、 removeQuerySettingsを使用します。 クエリ設定を取得するには、集計パイプラインの$querySettingsステージを使用します。
構文
このセクションに示されている 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> } } )
クエリシェイプハッシュを渡してクエリ設定を設定する
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> } } )
クエリシェイプ ハッシュは、クエリシェイプを一意に識別する string です。 クエリシェイプハッシュの例は"F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"です。
クエリシェイプ ハッシュstringを取得するには、次のいずれかを実行します。
集計パイプライン
$querySettingsの ステージを使用し、queryShapeHashフィールドを調べます。データベースプロファイラーの出力を調べます。
低速クエリ ログの表示
ハッシュstringを使用してクエリ設定を設定すると、$querySettings 集計ステージの出力に representativeQuery フィールドは表示されません。
Tip
どちらの構文バリエーションでも、 indexHintsドキュメントの配列を提供できます。 indexHintsドキュメントを 1 つだけ提供する場合は、配列括弧を省略できます。
コマンドフィールド
このコマンドは、次のフィールドを取ります。
フィールド | フィールドタイプ（ドキュメント、string、...） | 必要性 | 説明 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
setQuerySettings | ドキュメントまたは string は、 | 必須 | |||||||||
indexHints.ns | ドキュメント | 任意 | インデックス ヒントの名前空間。 オプションのインデックス ヒントが指定されている場合にのみ必要です。
| ||||||||
indexHints.allowedIndexes | 配列 | 任意 | インデックス ヒント用のインデックスの配列。 インデックスのヒントは、次のいずれかになります。
詳細については、「インデックスと | ||||||||
queryFramework | string | 任意 | クエリフレームワークstringは次のように設定できます。
| ||||||||
reject | ブール値 | 任意 |
デフォルトは、 クエリシェイプを有効にするには、クエリシェイプに対して
|
例
次の例では、 コレクションを作成し、さまざまなコマンドのクエリ設定を追加します。 の例では、クラスターで実行されるクエリシェイプのすべての実行に対して 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です。
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" } } )
（オプション）クエリ設定を確認します
この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' }, ... } ... ] } }
（任意）クエリを実行する
次の例では、 クエリを実行します。
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') } ]
（任意）クエリ設定を取得する
次の例では、集計パイプラインの$querySettingsステージを使用してクエリ設定を取得します。
db.aggregate( [ { $querySettings: {} } ] )
切り捨てられた出力（ 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' } } ]
個別のコマンドのクエリ設定を追加する
次の例では、 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" } } )
集計コマンドのクエリ設定を追加しました
次の例では、 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" } } )