setQuerySettings (데이터베이스 명령)

정의

setQuerySettings

버전 8.0에 추가 되었습니다.

setQuerySettings find, distinct 및 aggregate 명령에서 사용하는 쿼리 설정을 정의합니다.

쿼리 설정을 사용하여 인덱스 힌트를 추가하고, 작업 거부 필터를 정의하고, 클러스터에서 지정된 쿼리 형태 의 모든 실행에 대한 기타 필드를 설정할 수 있습니다. 클러스터의 쿼리 설정은 다시 시작해도 유지됩니다.

쿼리 옵티마이저 쿼리 계획 중에 쿼리 설정을 추가 입력으로 사용합니다. 쿼리 설정의 인덱스 힌트는 플래너가 사용할 수 있는 인덱스 설정하다 를 제한하지만 플래너가 인덱스 사용한다는 것을 보장하지는 않습니다. 플래너는 여전히 주어진 쿼리 형태 해시에 대한 성공적인 계획으로 컬렉션 스캔 선택할 수 있습니다.

클러스터 쿼리 설정은 명령 필드 로 전달된 쿼리 설정 또는 인덱스 힌트보다 우선합니다. 일치하는 쿼리 설정에 이미 인덱스 힌트가 포함된 경우 MongoDB 명령 필드 인덱스 힌트를 무시합니다.

인덱스 힌트는 쿼리 형태에 영향을 주지 않습니다.

힌트 및 쿼리 설정에 대한 자세한 내용은 쿼리 설정 구문 참조하세요.

참고

쿼리 설정을 제거 하려면 removeQuerySettings를 사용합니다. 현재 쿼리 설정을 확인하려면 집계 파이프라인에서 $querySettings 단계를 사용합니다.

쿼리 설정 및 인덱스 필터

MongoDB 8.0부터 인덱스 필터 는 더 이상 사용되지 않습니다. 대신 쿼리 설정을 사용하세요.

쿼리 설정에는 인덱스 필터보다 더 많은 기능이 있습니다. 인덱스 필터는 영구적이지 않으며 모든 클러스터 노드에 대한 인덱스 필터를 쉽게 만들 수 없습니다.

구문

이 섹션에 표시된 두 가지 구문 사양 중 하나를 사용하여 쿼리 설정을 추가하거나 업데이트 할 수 있습니다.

쿼리를 전달하여 쿼리 설정 지정

다음 구문에서는 다음을 제공합니다.

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

쿼리 형태 해시를 전달하여 쿼리 설정 지정

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

쿼리 형태 해시는 쿼리 형태 형태를 고유하게 식별하는 string 입니다. 쿼리 형태 해시의 예시 는 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C" 입니다.

쿼리 형태 해시 string 을 얻으려면 다음 중 하나를 수행합니다.

$querySettings 집계 파이프라인 에서 단계를 사용하고 queryShapeHash 필드 를 검사합니다.
데이터베이스 프로파일러 출력을 검사합니다.
느린 쿼리 로그를 확인합니다.

해시 문자열을 사용하여 쿼리 설정을 설정하다 경우 representativeQuery 필드 처음에는 $querySettings 집계 단계 출력에 표시되지 않습니다.

MongoDB 8.3부터 MongoDB 사용자가 설정하다 쿼리 설정의 representativeQuery 필드 를 쿼리 형태 해시로 백필합니다. MongoDB 쿼리 형태 와 일치하는 쿼리 실행할 때 백필을 예약합니다. 채우기에는 사용자의 조치 필요하지 않습니다.

백필은 쿼리에 대한 성능 영향 제한하기 위해 최선의 방식으로 비동기적으로 실행됩니다. 일치하는 쿼리 처음 실행될 때 쿼리 설정이 채워지는 것이 보장되지는 않습니다. 백필이 완료되지 않으면 MongoDB 다음에 일치하는 쿼리 실행될 때 백필을 다시 시도합니다.

추가 대표 쿼리를 보유하기 위해 MongoDB 8.3는 원래의 16MB BSON 문서 제한을 초과하여 쿼리 설정에서 대표 쿼리의 저장 용량 늘립니다.

팁

두 구문 변형 모두에서 indexHints 문서의 배열 을 제공할 수 있습니다. indexHints 문서 를 하나만 제공하는 경우 배열 괄호를 생략할 수 있습니다.

명령 필드

이 명령은 이러한 필드를 사용합니다.

필드

필드 유형

필요성

설명

setQuerySettings

문서 또는 문자열

필수 사항

다음 중 하나를 제공할 수 있습니다.

find, distinct 또는 aggregate 명령의 필드와 동일한 필드 및 원래 명령과 연결된 데이터베이스 가 있는 $db 필드 입니다.
쿼리 형태를 고유하게 식별하는 기존 쿼리 형태 쿼리 형태 문자열입니다. 쿼리 형태 해시의 예시 는 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"` 입니다.

indexHints.ns

문서

옵션

인덱스 힌트를 위한 네임스페이스입니다. 선택적 인덱스 힌트가 지정된 경우에만 필요합니다.

`db`	문자열	필수 사항	인덱스 힌트에 대한 데이터베이스 의 이름입니다.
`coll`	문자열	필수 사항	인덱스 힌트에 대한 컬렉션 의 이름입니다.

indexHints.allowedIndexes

배열

옵션

인덱스 힌트에 대한 인덱스 배열입니다. 인덱스 힌트는 다음 중 하나일 수 있습니다.

인덱스 이름
인덱스 키 패턴
$natural hint

자세한 내용은 인덱스 및 hint() 를 참조하세요.

queryFramework

문자열

옵션

쿼리 프레임워크 string 을 다음과 같이 설정하다 수 있습니다.

classic 클래식 엔진 을 사용합니다.
sbe 슬롯 기반 쿼리 실행 엔진 을 사용합니다. 자세한 내용은 슬롯 기반 쿼리 실행 엔진을 참조하세요.

reject

부울

옵션

true인 경우:

쿼리 형태 가 일치하는 새 쿼리는 거부되며 쿼리 응답 상태에서 쿼리 가 거부되었습니다.
현재 진행 중인 쿼리는 거부되지 않습니다.

기본값은 false입니다.

쿼리 형태를 활성화 하려면 쿼리 형태 쿼리 형태 대해 setQuerySettings 를 다시 실행 하고 reject 를 false 로 설정하다 합니다. reject 를 true 로 설정하다 한 다음 setQuerySettings 을 사용하여 false 로 다시 설정하면 다음과 같습니다.

settings 문서 가 비어 있지 않은 경우 setQuerySettings 는 쿼리 형태 를 활성화합니다.
settings 문서 에 reject: false 만 포함된 경우 setQuerySettings 는 오류를 반환합니다. 대신 removeQuerySettings 명령을 사용하여 설정을 제거 다음 setQuerySettings 를 사용하여 쿼리 설정을 추가합니다.

comment

BSON type

옵션

주석은 유효한 모든 BSON types일 수 있습니다. 예시 들어 문자열, 객체 등이 있습니다.

댓글을 사용하여 쿼리 설정에 대한 추가 정보를 제공할 수 있습니다. 예시 들어 쿼리 설정을 추가한 이유를 나타내는 문자열을 추가하려면 comment: "Index hint for orderDate_1 index to improve query performance"를 사용합니다.

댓글을 업데이트 하려면 setQuerySettings 를 다시 실행 하고 comment: { body: { msg: "Updated comment" } }을 사용합니다.

댓글을 제거 할 수는 없지만 공백 문자가 포함된 문자열로 설정하다 수는 있습니다. removeQuerySettings를사용하여 쿼리 설정을 제거 할 수 있습니다.

주석은 집계 파이프라인 $querySettings 단계 출력, explain() 명령 출력 및 느린 쿼리 로그에 나타납니다.

MongoDB 8.1 (및 8.0.4)부터 사용할 수 있습니다.

예시

다음 예제에서는 컬렉션 만들고 다양한 명령에 대한 쿼리 설정을 추가합니다. 이 예제에서는 클러스터 에서 쿼리 형태 실행하는 모든 경우에 대해 쿼리 플래너가 힌트 인덱스 또는 컬렉션 스캔 사용하도록 제한합니다.

예시 컬렉션 및 인덱스 만들기

실행:

 // 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 명령에 대한 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"
   }
} )

(선택 사항) 쿼리 설정 확인

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

(선택 사항) 쿼리 실행

다음 예시 에서는 쿼리 를 실행합니다.

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

고유 명령에 대한 쿼리 설정 추가

다음 예시 에서는 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"
   }
} )

애그리게이션 명령에 대한 쿼리 설정 추가

다음 예시 에서는 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