문서 홈 → 애플리케이션 개발 → MongoDB 매뉴얼
db.collection.replaceOne()
정의
db.collection.replaceOne(filter, replacement, options)
중요
Mongo쉬 방법
이 페이지에서는
mongosh
메서드를 설명합니다. 이는 데이터베이스 명령이나 Node.js와 같은 언어별 드라이버에 대한 설명서가 아닙니다 .데이터베이스 명령에 대해서는
update
명령을 참조하십시오.MongoDB API 드라이버의 경우 언어별 MongoDB 드라이버 설명서를 참조하세요.
레거시
mongo
셸 문서는 해당 MongoDB 서버 릴리스 문서를 참조하세요.필터를 기반으로 collection 내의 단일 문서를 교체합니다.
반환합니다: 다음이 포함된 문서입니다. 쓰기 고려로 작업이 실행된 경우 부울
acknowledged
을true
로, 쓰기 고려가 비활성화된 경우 부울을false
로 설정합니다.matchedCount
- 매칭된 문서의 수를 포함modifiedCount
- 수정된 문서 수를 포함upsertedId
upserted 문서의_id
이(가) 포함된 [upsertedId]
호환성
다음 환경에서 호스팅되는 배포에 db.collection.replaceOne()
사용할 수 있습니다.
MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스
MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전
구문
replaceOne()
메서드의 형식은 다음과 같습니다.
db.collection.replaceOne( <filter>, <replacement>, { upsert: <boolean>, writeConcern: <document>, collation: <document>, hint: <document|string> // Available starting in 4.2.1 } )
replaceOne()
메서드는 다음 매개 변수를 사용합니다.
매개변수 | 유형 | 설명 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
문서 | ||||||||||||
replacement | 문서 | 대체 문서입니다. 업데이트 연산자를 포함할 수 없습니다. | ||||||||||
upsert | 부울 | 선택 사항.
업서트가 여러 번 발생하지 않도록 하려면 기본값은 | ||||||||||
writeConcern | 문서 | 선택 사항입니다. 쓰기 고려를 표현하는 문서입니다. 기본 쓰기 고려를 사용하지 않으려면 생략하세요. 트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요. | ||||||||||
collation | 문서 | 선택 사항. 작업에 사용할 데이터 정렬을 지정합니다. 데이터 정렬을 사용하면 대소문자 및 악센트 표시 규칙과 같은 문자열 비교에 대한 언어별 규칙을 지정할 수 있습니다. 데이터 정렬 옵션의 구문은 다음과 같습니다:
데이터 정렬을 지정할 때 데이터 정렬이 지정되지 않았지만 컬렉션에 기본 데이터 정렬이 있는 경우( 컬렉션 또는 연산에 대한 데이터 정렬이 지정되지 않은 경우, MongoDB는 이전 버전에서 문자열 비교에 사용된 간단한 이진 비교를 사용합니다. 한 연산에 대해 여러 데이터 정렬을 지정할 수 없습니다. 예를 들어 필드별로 서로 다른 데이터 정렬을 지정할 수 없으며 정렬과 함께 찾기를 수행하는 경우 찾기 와 정렬에서 각각 다른 데이터 정렬을 사용하는 것은 허용되지 않습니다. 버전 3.4에 새로 추가되었습니다. | ||||||||||
문서 | 선택 사항.필터 를 지원하는 데 사용할 인덱스 를 지정하는 문서 또는 문자열입니다. 이 옵션은 인덱스 사양 문서 또는 인덱스 이름 문자열을 사용할 수 있습니다. 존재하지 않는 인덱스를 지정하면 연산 오류가 발생합니다. 예시 는 |
행동
replaceOne()
은 filter
와 일치하는 컬렉션의 첫 번째 일치 문서를 replacement
문서를 사용하여 대체합니다.
upsert
upsert: true
이고 filter
과 일치하는 문서가 없는 경우 db.collection.replaceOne()
는 replacement
문서를 기반으로 새 문서를 만듭니다.
샤드된 컬렉션에 upsert: true
를 지정하는 경우 filter
에 전체 샤드 키를 포함해야 합니다. 샤드된 컬렉션에 대한 추가 db.collection.replaceOne()
동작은 샤드된 컬렉션을 참조하세요 .
고정 사이즈 컬렉션
바꾸기 작업으로 인해 문서 크기가 변경되면 작업이 실패합니다.
Time Series 컬렉션
time series 컬렉션 에서는 replaceOne()
메서드를 사용할 수 없습니다.
샤드 컬렉션
MongoDB 4 부터 시작.2 db.collection.replaceOne()
은 먼저 쿼리 필터를 사용하여 단일 샤드를 대상으로 시도합니다. 작업이 쿼리 필터로 단일 샤드를 대상으로 지정할 수 없는 경우 대체 문서로 대상을 지정하려고 시도합니다.
이전 버전에서는 작업이 교체 문서를 사용하여 대상을 지정하려고 시도했습니다.
대체 문서의 샤드 키 요구 사항
교체 문서에는 샤드 키가 포함될 필요가 없습니다.
경고
샤드 collection의 문서에는 샤드 키 필드가 누락될 수 있습니다. 문서의 샤드 키 값을 변경할 때 실수로 샤드 키를 제거하지 않도록 주의하세요.
upsert
샤드 컬렉션에서
MongoDB 4 2부터 시작.db.collection.replaceOne()
,upsert: true
샤드된 컬렉션에 을 포함하는 작업은 에 전체 샤드 키를 포함해야 filter
합니다.
그러나, 샤드 collection의 문서 에는 샤드 키 필드가 누락 될 수 있습니다. 샤드 키가 누락된 document를 대상으로 지정하려면 null
동등성 매치 를 다른 필터 조건(예: _id
필드) 과 함께 사용할 수 있습니다. 예를 들면 다음과 같습니다.
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
샤드 키 수정
MongoDB 4.2부터는 샤드 키 필드가 변경할 수 없는 _id
필드가 아닌 경우 문서의 샤드 키 값을 업데이트할 수 있습니다. MongoDB 4.2 이하에서는 문서의 샤드 키 필드 값이 변경되지 않습니다.
경고
샤드 collection의 문서에는 샤드 키 필드가 누락될 수 있습니다. 문서의 샤드 키 값을 변경할 때 실수로 샤드 키를 제거하지 않도록 주의하세요.
을 사용하여 기존 샤드 키 값을 수정하려면 db.collection.replaceOne()
다음을 수행합니다.
누락된 샤드 키
샤드 컬렉션의 문서 에는 샤드 키 db.collection.replaceOne()
필드가 누락 될 수 있습니다. 를 사용하여 문서의 누락된 샤드 키를 설정하려면 mongos
에서 실행 해야 합니다 . 샤드에서 직접 작업을 실행하지 마세요 .
또한 다음 요구 사항도 적용됩니다.
팁
누락된 키 값은 null 동등 일치의 일부로 반환되므로 null 값 키가 업데이트되지 않도록 하려면 추가 쿼리 조건(예: _id
필드)을 적절히 포함하세요.
다음도 참조하세요.
트랜잭션
db.collection.replaceOne()
는 분산 트랜잭션 내에서 사용할 수 있습니다.
중요
대부분의 경우 분산 트랜잭션은 단일 문서 쓰기에 비해 더 큰 성능 비용이 발생하므로 분산 트랜잭션의 가용성이 효과적인 스키마 설계를 대체할 수는 없습니다. 대부분의 시나리오에서 비정규화된 데이터 모델 (내장된 문서 및 배열) 은 계속해서 데이터 및 사용 사례에 최적일 것입니다. 즉, 대부분의 시나리오에서 데이터를 적절하게 모델링하면 분산 트랜잭션의 필요성이 최소화됩니다.
추가 트랜잭션 사용 고려 사항(예: 런타임 제한 및 oplog 크기 제한)은 프로덕션 고려사항을 참조하세요.
트랜잭션 내 업서트
트랜잭션이 교차 샤드 쓰기 트랜잭션(write transaction)이 아닌 경우 분산 트랜잭션 내에서 컬렉션과 인덱스를 생성할 수 있습니다.
db.collection.replaceOne()
가 포함된 은 upsert: true
기존 컬렉션 또는 존재하지 않는 컬렉션에서 실행할 수 있습니다. 존재하지 않는 컬렉션에서 실행하면 작업이 컬렉션을 만듭니다.
팁
다음도 참조하세요.
쓰기 고려 및 트랜잭션
트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요.
예제
바꾸기
restaurant
컬렉션에는 다음 문서가 포함되어 있습니다.
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }
다음 작업은 name: "Central Perk Cafe"
가 있는 단일 문서를 대체합니다.
try { db.restaurant.replaceOne( { "name" : "Central Perk Cafe" }, { "name" : "Central Pork Cafe", "Borough" : "Manhattan" } ); } catch (e){ print(e); }
이 연산은 다음을 반환합니다.
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
일치하는 항목이 없으면 작업은 대신 다음을 반환합니다.
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }
upsert: true
를 설정하면 일치하는 항목이 없는 경우 문서가 삽입됩니다. 업서트로 바꾸기를참조하세요.
업서트로 바꾸기
restaurant
컬렉션에는 다음 문서가 포함되어 있습니다.
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }
다음 연산은 name : "Pizza Rat's Pizzaria"
인 문서를 upsert : true
로 바꾸려고 시도합니다.
try { db.restaurant.replaceOne( { "name" : "Pizza Rat's Pizzaria" }, { "_id": 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 }, { upsert: true } ); } catch (e){ print(e); }
upsert : true
이후 문서는 replacement
문서를 기준으로 삽입됩니다. 이 작업은 다음을 반환합니다.
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0, "upsertedId" : 4 }
이제 컬렉션에 다음 문서가 포함됩니다.
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }, { "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 }
쓰기 고려로 바꾸기
3명으로 구성된 멤버 복제본 세트가 있는 경우 다음 작업은 majority
의 w
및 100
의 wtimeout
을 지정합니다.
try { db.restaurant.replaceOne( { "name" : "Pizza Rat's Pizzaria" }, { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 }, { w: "majority", wtimeout: 100 } ); } catch (e) { print(e); }
확인이 wtimeout
제한보다 오래 걸리면 다음 예외가 발생합니다.
WriteConcernError({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })
다음 표에서는 errInfo.writeConcern.provenance
의 가능한 값에 대해 설명합니다.
출처 | 설명 |
---|---|
clientSupplied | 쓰기 우려 사항은 애플리케이션에서 지정되었습니다. |
customDefault | 쓰기 고려는 사용자 정의된 기본값에서 비롯된 것입니다. setDefaultRWConcern 을 참조하십시오. |
getLastErrorDefaults | 쓰기 고려는 복제본 세트의 settings.getLastErrorDefaults 필드에서 발생했습니다. |
implicitDefault | 쓰기 고려는 다른 모든 쓰기 고려 사양이 없는 상태에서
서버에서 발생했습니다. |
데이터 정렬 지정
버전 3.4에 새로 추가되었습니다.
데이터 정렬을 사용하면 대소문자 및 악센트 표시 규칙과 같은 문자열 비교에 대한 언어별 규칙을 지정할 수 있습니다.
컬렉션 myColl
에는 다음 문서가 있습니다.
{ _id: 1, category: "café", status: "A" } { _id: 2, category: "cafe", status: "a" } { _id: 3, category: "cafE", status: "a" }
다음 작업에는 데이터 정렬 옵션이 포함됩니다.
db.myColl.replaceOne( { category: "cafe", status: "a" }, { category: "cafÉ", status: "Replaced" }, { collation: { locale: "fr", strength: 1 } } );
replaceOne
에 hint
지정
버전 4.2.1에 추가되었습니다.
다음 문서로 샘플 members
컬렉션을 생성합니다.
db.members.insertMany([ { "_id" : 1, "member" : "abc123", "status" : "P", "points" : 0, "misc1" : null, "misc2" : null }, { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }, { "_id" : 3, "member" : "lmn123", "status" : "P", "points" : 0, "misc1" : null, "misc2" : null }, { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20, "misc1" : "Deactivated", "misc2" : null }, { "_id" : 5, "member" : "ijk123", "status" : "P", "points" : 0, "misc1" : null, "misc2" : null }, { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" } ])
컬렉션에 다음 인덱스를 만듭니다.
db.members.createIndex( { status: 1 } ) db.members.createIndex( { points: 1 } )
다음 업데이트 작업은 인덱스 {
status: 1 }
을(를) 사용하도록 명시적으로 암시합니다.
참고
존재하지 않는 인덱스를 지정하면 연산 오류가 발생합니다.
db.members.replaceOne( { "points": { $lte: 20 }, "status": "P" }, { "misc1": "using index on status", status: "P", member: "replacement", points: "20"}, { hint: { status: 1 } } )
이 연산은 다음을 반환합니다:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
사용된 인덱스를 보려면 $indexStats
파이프라인을 사용할 수 있습니다.
db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )