Docs Menu
Docs Home
/
MongoDB 매뉴얼
/ / /

콜모드

이 페이지의 내용

  • 정의
  • 호환성
  • 구문
  • 옵션
  • 인덱스 속성 변경
  • 문서 유효성 검사
  • 뷰 수정
  • Time Series 컬렉션 수정
  • 제한 컬렉션 크기 조정
  • 전후 이미지를 포함하는 문서의 Change Streams
  • 댓글 첨부
  • 쓰기 고려
  • 액세스 제어
  • 행동
  • 리소스 잠금
  • 예시
  • 인덱스의 만료 값 변경
  • 쿼리 플래너에서 인덱스 숨기기
collMod

collMod 를 사용하면 컬렉션에 옵션을 추가하거나 보기 정의를 수정할 수 있습니다.

mongosh에서 이 명령은 hideIndex()unhideIndex() 도우미 메서드를 통해 실행할 수도 있습니다.

헬퍼 메서드는 mongosh 사용자에게 편리하지만 데이터베이스 명령과 동일한 수준의 정보를 반환하지 못할 수 있습니다. 편의가 필요하지 않거나 추가 리턴 필드가 필요한 경우 데이터베이스 명령을 사용합니다.

참고

collMod 에 의해 수정된 뷰는 구체화된 뷰를 참조하지 않습니다. 온디맨드 구체화된 보기에 대한 설명은 $merge을(를) 대신 참조하십시오.

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

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

참고

이 명령은 모든 MongoDB Atlas 클러스터에서 지원됩니다. 모든 명령에 대한 Atlas 지원 에 대한 자세한 내용은 지원되지 않는 명령을 참조하세요.

명령은 다음과 같은 구문을 가집니다:

db.runCommand(
{
collMod: <collection or view>,
<option1>: <value1>,
<option2>: <value2>,
...
}
)

<collection or view>에 현재 데이터베이스에 있는 컬렉션 또는 뷰의 이름을 지정합니다.

인덱스 옵션을 변경하려면 변경하려는 기존 인덱스 옵션의 키 패턴 또는 이름을 지정합니다.

db.runCommand( {
collMod: <collection>,
index: {
keyPattern: <index_spec> | name: <index_name>,
expireAfterSeconds: <number>, // Set the TTL expiration threshold
hidden: <boolean>, // Change index visibility in the query planner
prepareUnique: <boolean>, // Reject new duplicate index entries
unique: <boolean> // Convert an index to a unique index
},
dryRun: <boolean>
} )

인덱스가 존재하지 않으면 "cannot find index <name|keyPattern> for ns <db.collection>" 메시지와 함께 명령에 오류가 발생합니다.

index

index 옵션은 기존 인덱스의 다음 속성을 변경할 수 있습니다.

인덱스 속성
설명
expireAfterSeconds

TTL 컬렉션의 만료 임계값을 결정하는 시간(초)입니다.

제대로 실행되면 다음 항목이 포함된 문서가 반환됩니다.

  • expireAfterSeconds_new다음에 대한 새로운 값 expireAfterSeconds

  • expireAfterSeconds_oldexpireAfterSeconds는 인덱스에 이전에 expireAfterSeconds 값이 있었던 경우의 이전 값입니다.

인덱스 옵션 expireAfterSeconds를 수정하면 인덱스의 $indexStats가 재설정됩니다.

MongoDB 5.0 이전에 생성된 TTL 인덱스를 사용하거나 MongDB 5.0에서 생성된 데이터를 5.0 이전 설치와 동기화하려는 경우 잘못된 구성 문제를 방지하려면 NaN을 사용하여 구성된 인덱스를 참조하세요.

TTL 인덱스 expireAfterSeconds 값은 02147483647 사이여야 합니다.

hidden

쿼리 플래너에서 인덱스를 숨길지 여부를 결정하는 부울입니다.

hidden 값이 변경되면 명령은 변경된 속성에 대한 이전 값(hidden_old)과 새 값(hidden_new)이 모두 포함된 문서를 반환합니다.

그러나 hidden 값이 변경되지 않은 경우(즉 이미 숨겨진 인덱스를 숨기거나 이미 숨기지 않은 인덱스를 숨기지 않는 경우), 이 명령은 출력에서 hidden_oldhidden_new 필드를 생략합니다.

인덱스를 숨기려면 featureCompatibilityVersion4.4 이상으로 설정해야 합니다.

인덱스 옵션 hidden을 수정하면 값이 변경되는 경우 인덱스의 $indexStats가 재설정됩니다.

prepareUnique

인덱스가 새로운 중복 항목을 허용할지 여부를 결정하는 부울입니다.

prepareUnique true인 경우 DuplicateKey 오류로 인해 새 중복 항목이 실패합니다. 결과 인덱스는 고유 인덱스로 변환할 수 있습니다. 인덱스를 변환하려면 unique 옵션과 함께 collMod를 사용합니다.

기존 인덱스가 업데이트되어 prepareUniquetrue인 경우 인덱스에 기존의 중복 인덱스 항목이 있는지 확인되지 않습니다.

버전 6.0에 추가.

unique

인덱스가 고유한지 여부를 판단하는 부울입니다.

false 값은 지원되지 않습니다.

uniquetrue인 경우 collModkeyPattern 인덱스에서 중복을 검색한 다음 중복 인덱스 항목이 없는 경우 고유 인덱스로 변환합니다.

초기 스캔 중에 중복 항목이 감지되면 collModCannotConvertIndexToUnique 및 충돌하는 문서 목록을 반환합니다. 항목이 중복된 인덱스를 고유 인덱스로 변환하려면 보고된 충돌을 모두 수정하고 collMod를 다시 실행하세요.

전환을 종료하려면 prepareUniquefalse로 설정합니다.

고유하지 않은 색인을 고유 인덱스로 변환하는 방법의 예시를 보려면 기존 색인을 고유 인덱스로 변환하기를 참조하세요.

버전 6.0에 추가.

dryRun

기본값: false

index.uniquetrue인 경우에만 사용됩니다.

고유하지 않은 인덱스를 고유 인덱스로 변환하기 전에 collMod 명령을 dryRun: true와 함께 실행할 수 있습니다. 이렇게 하면 MongoDB가 컬렉션에 중복 키가 있는지 확인하고 위반 사항이 있으면 반환합니다.

인덱스를 오류 없이 고유한 인덱스로 변환할 수 있는지 확인하려면 dryRun: true를 사용합니다.

validator

validator 사용 시 사용자가 컬렉션에 대한 유효성 검사 규칙 또는 표현식을 지정할 수 있습니다.

validator 옵션은 유효성 검사 규칙 또는 표현식을 지정하는 문서를 사용합니다. $near, $nearSphere, $text, $where을(를) 제외하고 쿼리 연산자와 동일한 연산자를 사용하여 표현식을 지정할 수 있습니다.

참고

  • 유효성 검사는 업데이트 및 삽입 중에 수행됩니다. 기존 문서는 수정될 때까지 유효성 검사를 거치지 않습니다.

  • admin, localconfig 데이터베이스의 컬렉션에는 유효성 검사기를 지정할 수 없습니다.

  • system.* 컬렉션에 대한 유효성 검사기를 지정할 수 없습니다.

validationLevel

validationLevel 는 MongoDB가 업데이트 중에 기존 문서에 유효성 검사 규칙을 얼마나 엄격하게 적용하는지 결정합니다.

"off"
삽입 또는 업데이트에 대한 유효성 검사가 없습니다.
"strict"
기본값 모든 삽입 및 모든 업데이트에 유효성 검사 규칙을 적용합니다.
"moderate"
기존의 유효한 문서에 대한 삽입 및 업데이트에 유효성 검사 규칙을 적용합니다. 기존의 유효하지 않은 문서에 대한 업데이트에는 규칙을 적용하지 마세요.

validationLevel 사용 예시는 기존 문서에 대한 유효성 검사 수준 지정을 참조하세요.

validationAction

validationAction 옵션은 유효하지 않은 문서에 대해 error를 반환할지 또는 유효하지 않은 문서를 허용하되 위반에 대해 warn를 제공할지 여부를 결정합니다.

중요

문서 유효성 검사는 validationLevel에 의해 결정된 문서에만 적용됩니다.

validationAction 사용 예시는 유효하지 않은 문서 처리 방법 선택을 참조하세요.

참고

이 명령으로 수정된 뷰는 구체화된 뷰를 참조하지 않습니다. 온디맨드 구체화된 보기에 대한 설명은 $merge 대신 참조하세요.

viewOn

기본 소스 컬렉션 또는 보기입니다. 보기 정의는 지정된 pipeline을 이 소스에 적용함으로써 결정됩니다.

액세스 제어를 사용하여 실행 중인 MongoDB deployment에서 보기를 수정하는 경우 반드시 필요합니다.

pipeline

를 정의하는 집계 파이프라인입니다.

참고

보기 정의 pipeline에는 $out 또는 $merge 단계를 포함할 수 없습니다. 이 제한은 $lookup 단계 또는 $facet 단계에서 사용되는 파이프라인과 같은 임베디드 파이프라인에도 적용됩니다.

액세스 제어를 사용하여 실행 중인 MongoDB deployment에서 보기를 수정하는 경우 반드시 필요합니다.

뷰 정의는 공개입니다. 즉, 뷰에 대한 db.getCollectionInfos()explain 작업에는 뷰를 정의하는 파이프라인이 포함됩니다. 따라서 뷰 정의에 민감한 필드와 값을 직접 참조하지 않는 것이 좋습니다.

db.runCommand( {
collMod: "myView",
viewOn: "activities",
pipeline: [
{ $match: { status: "Q" } },
{ $project: { user: 1, date: 1, description: 1} } ]
} )
expireAfterSeconds

참고

이는 TTL 컬렉션의 만료 시간을 변경하기 위해 expireAfterSeconds 속성과 함께 index 옵션을 사용하는 것과 다릅니다.

문서 자동 제거를 활성화하거나 time series 컬렉션의 현재 만료 간격을 수정하려면 expireAfterSeconds 값을 변경하세요:합니다.

db.runCommand( {
collMod: <collection>,
expireAfterSeconds: <number> | "off"
} )

자동 제거를 사용하지 않으려면 expireAfterSeconds ~ "off" 을 설정하고, 문서가 만료되는 시간(초)을 지정하려면 음수가 아닌 소수점(>=0)을 설정합니다.

다음도 참조하세요.

granularity

time series 컬렉션의 세분성을 수정하려면 timeseries.granularity를 더 짧은 시간 단위에서 더 긴 단위로 늘릴 수 있습니다.

db.runCommand( {
collMod: "weather24h",
timeseries: { granularity: "seconds" | "minutes" | "hours" }
} )

대신 사용자 지정 버킷팅 필드 bucketRoundingSecondsbucketMaxSpanSeconds granularity를 업데이트하려면 명령에 두 사용자 지정 필드를 모두 collMod 포함하고 동일한 값으로 설정합니다.

db.runCommand( {
collMod: "weather24h",
timeseries: {
bucketRoundingSeconds: 86400,
bucketMaxSpanSeconds: 86400
}
} )

세분화 간격이나 사용자 지정 버킷팅 값은 줄일 수 없습니다.

중요

time-series collection에 사용자 지정 버킷팅 필드 bucketMaxSpanSecondsbucketRoundingSeconds 가 명시적으로 지정되어 있는 경우 MongoDB 6.3 이하로 다운그레이드할 수 없습니다. 가능한 경우 해당 granularity 로 변환합니다. 그럴 수 없는 경우에는 다운그레이드하기 전에 collection을 삭제해야 합니다.

컬렉션을 사용자 지정 버킷에서 granularity로 변환하려면 bucketMaxSpanSecondsbucketRoundingSeconds 값이 모두 granularity에 해당하는 값보다 작거나 같아야 합니다.

granularity
bucketRoundingSeconds 한도(포함)
bucketMaxSpanSeconds 한도(포함)
seconds
60
3,600
minutes
3,600
86,400
hours
86,400
2592000

다음도 참조하세요.

버전 6.0에 추가.

MongoDB 6.0부터는 제한이 있는 컬렉션의 크기를 조정할 수 있습니다. 제한된 컬렉션의 최대 크기를 바이트 단위로 변경하려면 cappedSize 옵션을 사용합니다. 기존 제한 고정 사이즈 컬렉션의 최대 문서 수를 변경하려면 cappedMax 옵션을 사용하세요.

참고

이러한 명령을 사용하여 oplog의 크기를 조정할 수 없습니다. 대신 replSetResizeOplog를 사용하세요.

cappedSize

고정 사이즈 컬렉션의 새 최대 크기를 바이트 단위로 지정합니다. cappedSize0보다 크고 1e+15(1PB)보다 작아야 합니다.

cappedMax

고정 사이즈 컬렉션의 새로운 최대 문서 수를 지정합니다. 0}을 보다 작게 설정하면 제한이 없음을 cappedMax 의미합니다.0

예를 들어 다음 명령은 제한 컬렉션의 최대 크기를 100,000바이트로 설정하고 컬렉션의 최대 문서 수를 500개로 설정합니다.

db.runCommand( {
collMod: <collection>,
cappedSize: 100000,
cappedMax: 500
} )

버전 6.0에 추가.

changeStreamPreAndPostImages

MongoDB 6.0부터는 변경 스트림 이벤트를 사용하여 문서의 변경 전후 버전(문서의 전후 이미지)을 출력할 수 있습니다.

  • 사전 이미지는 문서가 교체, 업데이트 또는 삭제되기 전의 문서입니다. 삽입된 문서에는 사전 이미지가 없습니다.

  • 사후 이미지는 문서가 삽입, 교체, 업데이트된 후의 문서입니다. 삭제된 문서에 대한 사후 이미지가 없습니다.

  • db.createCollection(), create 또는 collMod를 사용하여 컬렉션에 대해 changeStreamPreAndPostImages를 활성화합니다.

collMod를 사용하여 컬렉션의 변경 스트림 사전 및 사후 이미지 변경을 활성화하려면 changeStreamPreAndPostImages 필드를 사용합니다.

db.runCommand( {
collMod: <collection>,
changeStreamPreAndPostImages: { enabled: <boolean> }
} )

컬렉션의 변경 스트림 사전 및 사후 이미지를 활성화하려면 changeStreamPreAndPostImages를(을) true로 설정합니다. 예시:

db.runCommand( {
collMod: "orders",
changeStreamPreAndPostImages: { enabled: true }
} )

컬렉션의 변경 스트림 사전 및 사후 이미지를 비활성화하려면 changeStreamPreAndPostImagesfalse로 설정합니다. 예시:

db.runCommand( {
collMod: "orders",
changeStreamPreAndPostImages: { enabled: false }
} )

이미지가 다음과 같은 경우 변경 스트림 이벤트에 사전 및 사후 이미지를 사용할 수 없습니다.

  • 문서 업데이트 또는 삭제 작업 시 collection에서 활성화되지 않았습니다.

  • expireAfterSeconds에서 전후 이미지 보존 시간 설정 이후에 제거됩니다.

    • 다음 예시에서는 전체 클러스터에서 expireAfterSeconds100초로 설정합니다.

      use admin
      db.runCommand( {
      setClusterParameter:
      { changeStreamOptions: {
      preAndPostImages: { expireAfterSeconds: 100 }
      } }
      } )
    • 다음 예시에서는 expireAfterSeconds 등 현재 changeStreamOptions 설정을 반환합니다.

      db.adminCommand( { getClusterParameter: "changeStreamOptions" } )
    • expireAfterSecondsoff로 설정하면 기본 보존 정책이 사용되며, 해당 변경 스트림 이벤트가 oplog에서 제거될 때까지 사전 및 사후 이미지가 보존됩니다.

    • 변경 스트림 이벤트가 oplog에서 제거되면 expireAfterSeconds 사전 및 사후 이미지 보존 시간에 관계없이 해당 사전 및 사후 이미지도 삭제됩니다.

추가 고려 사항

  • 전후 이미지를 활성화하면 저장 공간이 소모되고 처리 시간이 늘어납니다. 필요한 경우에만 전후 이미지를 활성화하세요.

  • 변경 스트림 이벤트 크기를 16메가바이트 미만으로 제한합니다. 이벤트 크기를 제한하려면 다음을 수행하면 됩니다.

    • 문서 크기를 8메가바이트로 제한합니다. updateDescription과 같은 다른 변경 스트림 이벤트 필드가 크지 않은 경우 변경 스트림 출력에서 사전 및 사후 이미지를 동시에 요청할 수 있습니다.

    • updateDescription과 같은 다른 변경 스트림 이벤트 필드가 크지 않은 경우 최대 16메가바이트 문서에 대해 변경 스트림 출력에서 사후 이미지만 요청합니다.

    • 다음과 같은 경우 최대 16메가바이트의 문서에 대해 변경 스트림 출력에서 사전 이미지만 요청합니다.

      • 문서 업데이트가 문서 구조나 내용의 작은 부분에만 영향을 미칩니다. 그리고

      • replace 변경 이벤트를 발생시키지 않습니다. replace 이벤트에는 항상 후이미지가 포함됩니다.

  • 사전 이미지를 요청하려면 db.collection.watch()에서 fullDocumentBeforeChangerequired 또는 whenAvailable로 설정합니다. 사후 이미지를 요청하려면 동일한 방법으로 fullDocument를 설정합니다.

  • 사전 이미지가 config.system.preimages 컬렉션에 기록됩니다.

    • config.system.preimages collection은 커질 수 있습니다. collection 크기를 제한하려면 앞서 표시된 대로 사전 이미지에 대해 expireAfterSeconds 시간을 설정할 수 있습니다.

    • 사전 이미지는 백그라운드 프로세스가 비동기적으로 제거합니다.

중요

이전 버전과 호환되지 않는 기능

MongoDB 6.0부터 변경 스트림에 문서 사전 및 사후 이미지를 사용하는 경우 이전 MongoDB 버전으로 다운그레이드하기 전에 collMod 명령을 사용하여 각 컬렉션에 대해changeStreamPreAndPostImages를 비활성화해야 합니다.

다음도 참조하세요.

comment

선택 사항. 이 명령에 댓글을 첨부할 수 있습니다. 댓글은 최상위 필드여야 하며 유효한 모든 BSON types일 수 있습니다. 지정한 설명은 다음 위치에서 이 명령의 레코드와 함께 표시됩니다.

w

선택 사항. collMod명령의 쓰기 관련 사항을 표현하는 문서입니다.

기본 쓰기 고려를 사용하지 않으려면 생략합니다.

배포에서 인증/권한 부여를 집행하는 경우 collMod 명령을 실행하려면 다음 권한이 있어야 합니다.

작업
필수 권한
미고정 사이즈 컬렉션 수정
collMod 데이터베이스
뷰 수정

collMod 데이터베이스에서 다음 중 하나를 수행합니다.

  • 수정할 뷰에 find없거나

  • 수정할 뷰의 find와 소스 컬렉션/뷰의 find를 모두 입력합니다.

기본 제공 역할 dbAdmin은 이러한 권한을 제공합니다.

collMod 명령은 작업 기간 동안 지정된 컬렉션에 대한 컬렉션 잠금을 가져옵니다.

다음 예시에서는 이름이 user_log인 컬렉션에서 기존 TTL 인덱스 { lastAccess: 1 }expireAfterSeconds 속성을 업데이트합니다. 인덱스의 현재 expireAfterSeconds 속성은 1800초(또는 30분)로 설정되어 있으며 이 예시에서 값을 3600초(또는 60분)로 변경합니다.

db.runCommand({
collMod: "user_log",
index: {
keyPattern: { lastAccess: 1 },
expireAfterSeconds: 3600
}
})

작업이 성공하면 변경된 속성의 이전 값과 새 값이 모두 포함된 문서를 반환합니다.

{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }

참고

인덱스를 숨기려면 featureCompatibilityVersion5.0 이상으로 설정해야 합니다.

다음 예시는 orders 컬렉션의 기존 인덱스를 숨깁니다. 특히 이 작업은 쿼리 플래너에서 사양 { shippedDate: 1 }인 인덱스를 숨깁니다.

db.runCommand( {
collMod: "orders",
index: {
keyPattern: { shippedDate: 1 },
hidden: true
}
} )

작업이 성공하면 변경된 속성의 이전 값과 새 값이 모두 포함된 문서를 반환합니다.

{ "hidden_old" : false, "hidden_new" : true, "ok" : 1 }

참고

작업이 성공했지만 hidden 값이 변경되지 않은 경우(특히 이미 숨겨진 인덱스를 숨기거나 이미 숨겨진 인덱스를 숨기지 않은 경우), 명령은 출력에서 hidden_oldhidden_new 필드를 생략합니다.

텍스트 인덱스를 숨기려면 keyPattern가 아닌 name으로 인덱스를 지정해야 합니다.

돌아가기

cloneCollectionAsCapped