ANNOUNCEMENT: Voyage AI joins MongoDB to power more accurate and trustworthy AI applications on Atlas.
Learn more
Docs Menu
Docs Home
/
MongoDB 매뉴얼
/
참조
/
데이터베이스 명령
/
관리

setQuerySettings

이 페이지의 내용

정의

setQuerySettings

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

쿼리 설정을 사용하여 인덱스 힌트를 추가하고, 작업 거부 필터 를 정의하고, 기타 필드를 설정하다 수 있습니다. 설정은 전체 클러스터 의 쿼리 형태 에 적용 됩니다. 클러스터 는 종료 후에도 설정을 유지합니다.

예를 예시, 쿼리 설정을 통해 클러스터 내 쿼리 형태 의 모든 실행에 인덱스 를 사용할 수 있습니다.

쿼리 옵티마이저 쿼리 계획 중에 쿼리 설정을 추가 입력으로 사용하며, 이는 쿼리 를 실행 하기 위해 선택한 계획에 영향을 줍니다.

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

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

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

참고

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

구문

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

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

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

  • 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 을 얻으려면 다음 중 하나를 수행합니다.

해시 string 을 사용하여 쿼리 설정하다 을 지정하면 $querySettings 집계 단계 출력에 representativeQuery 필드 가 표시되지 않습니다.

팁

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

명령 필드

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

필드
필드 유형(문서, string, ...)
필요성
설명

setQuerySettings

문서 또는 문자열

필수 사항

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

  • find, distinct 또는 aggregate 명령의 필드와 동일한 필드 및 원래 명령과 연결된 데이터베이스 가 있는 $db 필드 입니다.

  • 쿼리 형태를 고유하게 식별하는 기존 쿼리 형태 쿼리 형태 문자열입니다. 쿼리 형태 해시의 예시 는 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"` 입니다.

indexHints.ns

문서

옵션

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

db

문자열

필수 사항

인덱스 힌트에 대한 데이터베이스 의 이름입니다.

coll

문자열

필수 사항

인덱스 힌트에 대한 컬렉션 의 이름입니다.

indexHints.allowedIndexes

배열

옵션

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

  • 인덱스 이름

  • 인덱스 키 패턴

  • $natural hint

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

queryFramework

문자열

옵션

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

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.0.4 부터 사용 가능합니다.

예시

다음 예제에서는 컬렉션 을 만들고 다양한 명령에 대한 쿼리 설정을 추가합니다. The examples use one index for all executions of a query shape run in the cluster.

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

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

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

자세히 알아보기

돌아가기

setDefaultRWConcern

다음

setUserWriteBlockMode