setQuerySettings (데이터베이스 명령)

정의

setQuerySettings

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

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

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

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

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

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

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

참고

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

쿼리 설정 및 인덱스 필터

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

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

호환성

이 명령은 다음 환경에서 호스팅되는 배포에서 사용할 수 있습니다.

MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스

중요

이 명령은 M0 및 Flex 클러스터에서 지원되지 않습니다. 자세한 내용은 지원되지 않는 명령을 참조하세요.

MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전

구문

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

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

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

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

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

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

MongoDB 8.3에서 시작하고,FCV 가 8.3 이상인 경우, MongoDB 쿼리 형태 해시로 설정하다 쿼리 설정에 대해 representativeQuery 필드 백필합니다. MongoDB 쿼리 형태 와 일치하는 쿼리 실행할 때 백필을 예약합니다. 채우기에는 사용자의 조치 필요하지 않습니다.

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

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

팁

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

명령 필드

setQuerySettings 명령의 settings 문서 다음 필드를 사용합니다.

필드	필드 유형	필요성	설명
`setQuerySettings`	문서 또는 문자열	필수 사항	다음 중 하나를 제공할 수 있습니다. `find`, `distinct` 또는 `aggregate` 명령의 필드와 동일한 필드 및 원래 명령과 연결된 데이터베이스 가 있는 `$db` 필드 입니다. 쿼리 형태를 고유하게 식별하는 기존 쿼리 형태 쿼리 형태 문자열입니다. 쿼리 형태 해시의 예시 는 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"` 입니다.
`indexHints.ns`	문서	옵션	인덱스 힌트를 위한 네임스페이스입니다. 선택적 인덱스 힌트가 지정된 경우에만 필요합니다.
`indexHints.ns.db`	문자열	조건부	인덱스 힌트에 대한 데이터베이스 의 이름입니다. `indexHints.ns`를 지정할 때 필요합니다.
`indexHints.ns.coll`	문자열	조건부	인덱스 힌트에 대한 컬렉션 의 이름입니다. `indexHints.ns`를 지정할 때 필요합니다.
`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() 명령 출력 및 느린 쿼리 로그에 나타납니다. 버전 8.1: (및 8.0.4)의 새로운 기능.
`queryKnobs`	문서	옵션	`setParameter`를 사용하여 인스턴스 전체에 적용하는 대신 이 쿼리 형태 에 대해서만 내부 서버 매개변수를 재정의하는 `{ <knobName>: <value> }` 쌍의 문서 입니다. 각 노브는 기본 서버 매개변수의 유형, 범위 및 기본값 유지합니다. Unlike the other `setQuerySettings` fields, which replace the entire value when set, `queryKnobs` merges with existing knob values. `setQuerySettings` changes the knobs you include in the `queryKnobs` document, and leaves all other knobs unchanged. `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부터는 queryKnobs 설정을 사용하여 전체 인스턴스 대신 단일 쿼리 형태 에 대한 내부 서버 매개변수를 재정의할 수 있습니다. 동일한 배포서버 에서 다른 워크로드의 동작을 변경하지 않고 하나의 회귀된 형태의 영향 완화하려면 타겟팅된 쿼리에 대한 queryKnobs 필드 설정합니다.

예시 들어 queryKnobs를 { noTableScan: true }로 설정하여 전체 인스턴스 대신 단일 쿼리 형태 에 대한 notablescan 서버 매개변수를 재정의할 수 있습니다.

각 노브는 기본 서버 매개변수의 유형, 범위 및 기본값 유지하며, setQuerySettings는 setParameter가 실행하는 것과 동일한 유효성 검사 실행합니다. setQuerySettings는 다음 값을 거부합니다.

알 수 없는 노브
쿼리 설정을 통해 설정 가능으로 표시되지 않은 노브
잘못된 BSON types
잘못된 열거형 형 문자열
범위를 벗어난 값
최소 FCV 요구 사항이 클러스터 FCV 를 초과하는 노브

노브의 유효 값은 가장 높은 것부터 가장 낮은 것까지 이 우선 순위를 따릅니다.

모양별 값은 다음으로 설정하다 . queryKnobs
다음으로 설정하다 인스턴스 전체 값 setParameter
컴파일된 기본값

쿼리 노브는 해시 쿼리 설정의 일부이므로 계획 캐시 키의 일부이기도 합니다. 노브 값을 변경하면 MongoDB 새 계획 캐시 키를 생성하므로 플래너는 오래된 캐시된 계획을 재사용하는 대신 새 계획을 만듭니다.

프로세스 별로 적용되고 노드마다 다를 수 있는 setParameter와 달리, MongoDB 일치하는 쿼리 형태 에 대해 전체 클러스터 에 동일한 queryKnobs 값을 적용합니다.

중요

FCV 9.0에서 이전 버전으로 다운그레이드하면 마이그레이션 저장된 쿼리 설정을 업데이트합니다. 마이그레이션 최소 FCV 대상 버전을 초과하는 모든 노브를 제거하고 여전히 기본값 만 포함하는 모든 설정 항목을 삭제합니다. 9.0(으)로 다시 업그레이드해도 제거된 노브는 복원 않습니다. setQuerySettings로 다시 적용해야 합니다.

예시

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

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

실행:

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