db.collection.insertMany()
드라이버가 포함된 MongoDB
이 페이지에서는 메서드를 mongosh
설명합니다. MongoDB 운전자 에서 이에 상응하는 메서드를 보려면 사용 중인 프로그래밍 언어 의 해당 페이지를 참조하세요.
정의
db.collection.insertMany()
collection에 여러 문서를 삽입할 수 있습니다.
반환합니다: 다음이 포함된 문서입니다.
acknowledged
부울로,true
작업이 쓰기 고려 (write concern) 로 실행된 경우 로 설정하다 되고,false
쓰기 고려 (write concern) 가 비활성화된 경우 로 설정됩니다.성공적으로 삽입된 각 문서에 대해
_id
값을 포함하는insertedIds
배열입니다.
호환성
이 메서드는 다음 환경에서 호스팅되는 배포에서 사용할 수 있습니다.
MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스
참고
이 명령은 모든 MongoDB Atlas 클러스터에서 지원됩니다. 모든 명령에 대한 Atlas 지원에 관해 자세히 알아보려면 지원되지 않는 명령을 참조하십시오.
MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전
구문
insertMany()
메서드의 구문은 다음과 같습니다.
db.collection.insertMany( [ <document 1> , <document 2>, ... ], { writeConcern: <document>, ordered: <boolean> } )
Parameter | 유형 | 설명 |
---|---|---|
| 문서 | 컬렉션에 삽입할 문서의 배열입니다. |
| 문서 | 선택 사항입니다. 쓰기 고려를 표현하는 문서입니다. 기본 쓰기 고려를 사용하지 않으려면 생략하세요. 트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요. |
| 부울 | 선택 사항. |
동작
문서 배열이 주어지면 insertMany()
(이)가 배열의 각 문서를 컬렉션에 삽입합니다.
연산 실행
기본적으로 문서는 순서대로 삽입됩니다.
ordered
를 false로 설정하다 하면 문서가 순서가 지정되지 않은 형식으로 삽입되고 성능 향상을 위해 mongod
에 의해 순서가 변경될 수 있습니다. 순서가 지정되지 않은 insertMany()
을(를) 사용하는 경우 애플리케이션은 삽입 순서에 의존해서는 안 됩니다.
각 그룹의 작업 수는 데이터베이스의 maxWriteBatchSize 값을 초과할 수 없습니다. MongoDB 3.6부터 이 값은 100,000
입니다. 이 값은 hello.maxWriteBatchSize
필드에 표시됩니다.
이 제한은 오류 메시지의 크기가 너무 커지는 문제를 방지합니다. 그룹이 이 제한을 초과하면 클라이언트 드라이버는 그룹을 제한 값보다 작거나 같은 수의 작은 그룹으로 나눕니다. 예를 들어 maxWriteBatchSize
값이 100,000
인 경우 대기열이 200,000
개의 작업으로 구성되어 있으면 드라이버는 각각 100,000
개의 작업이 있는 2개의 그룹을 만듭니다.
참고
이 드라이버는 고급 API를 사용할 때에만 그룹을 작은 그룹으로 나눕니다. db.runCommand() 를 직접 사용하는 경우(예: 드라이버를 작성할 때), 제한을 초과하는 쓰기 배치를 실행하려고 할 때 MongoDB에서 오류가 발생합니다.
MongoDB 3.6부터 단일 배치에 대한 오류 보고서가 너무 커지면 MongoDB는 나머지 모든 오류 메시지를 빈 문자열로 자릅니다. 현재는 총 크기가 1MB
보다 큰 오류 메시지가 2개 이상 있는 경우 시작됩니다.
크기 및 그룹화 메커니즘은 내부 성능 세부 정보이며 향후 버전에서 변경될 수 있습니다.
샤드 컬렉션에서 ordered
작업 목록을 실행하는 것은 unordered
목록을 실행하는 것보다 일반적으로 느립니다. 정렬된 목록에서는 각 작업이 이전 작업이 완료될 때까지 기다려야 하기 때문입니다.
컬렉션 생성
컬렉션이 존재하지 않으면 insertMany()
가 쓰기 성공 시 컬렉션을 생성합니다.
_id
필드
문서에 _id 필드가 지정되지 않은 경우 mongod
에서 _id
필드를 추가하고 문서에 고유한 ObjectId()
를 할당합니다. 대부분의 드라이버는 ObjectId를 생성하고 _id
필드를 삽입하지만, 드라이버나 애플리케이션이 수행하지 않는 경우 mongod
에서 _id
를 생성하여 채웁니다.
문서에 _id
필드가 포함된 경우 중복 키 오류를 방지하려면 _id
값이 컬렉션 내에서 고유해야 합니다.
설명 가능성
insertMany()
는 db.collection.explain()
과 호환되지 않습니다.
Error Handling
삽입으로 BulkWriteError
예외가 발생합니다.
쓰기 고려 오류를 제외하고 순서가 지정된 작업은 오류가 발생한 후 중지되고, 순서가 지정되지 않은 작업은 대기열에 남아 있는 모든 쓰기 작업을 계속 처리합니다.
쓰기 고려 오류는 writeConcernErrors
필드에 표시되고 기타 모든 오류는 writeErrors
필드에 표시됩니다. 오류가 발생하면 삽입된 _id 목록 대신 성공적인 쓰기 작업의 수가 표시됩니다. 순서가 지정된 작업은 발생한 단일 오류를 표시하고 순서가 지정되지 않은 작업은 배열에 각 오류를 표시합니다.
스키마 유효성 검사 오류
컬렉션이 스키마 유효성 검사를 사용하고 validationAction
을 error
로 설정한 경우 db.collection.insertMany()
로 잘못된 문서를 삽입하면 writeError
가 발생합니다. documents
배열에서 유효하지 않은 문서 앞에 오는 문서는 컬렉션에 기록됩니다. ordered
필드의 값은 나머지 유효한 문서가 삽입되는지 여부를 판별합니다.
트랜잭션
db.collection.insertMany()
는 분산 트랜잭션 내에서 사용할 수 있습니다.
중요
대부분의 경우 분산 트랜잭션은 단일 문서 쓰기에 비해 더 큰 성능 비용이 발생하므로 분산 트랜잭션의 가용성이 효과적인 스키마 설계를 대체할 수는 없습니다. 대부분의 시나리오에서 비정규화된 데이터 모델 (내장된 문서 및 배열) 은 계속해서 데이터 및 사용 사례에 최적일 것입니다. 즉, 대부분의 시나리오에서 데이터를 적절하게 모델링하면 분산 트랜잭션의 필요성이 최소화됩니다.
추가 트랜잭션 사용 고려 사항(예: 런타임 제한 및 oplog 크기 제한)은 프로덕션 고려사항을 참조하세요.
트랜잭션에서 컬렉션 생성
트랜잭션이 교차 샤드 쓰기 트랜잭션(write transaction)인 이 아닌 경우 분산 트랜잭션 내에서 컬렉션과 인덱스를 생성할 수 있습니다.
트랜잭션에서 존재하지 않는 컬렉션에 대한 삽입을 지정하면 MongoDB는 해당 컬렉션을 암시적으로 생성합니다.
쓰기 고려 및 트랜잭션
트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요.
무작위 데이터에 대한 성능 고려 사항
작업에서 인덱싱된 필드에 대량의 임의 데이터(예시: 해시 인덱스)를 삽입하는 경우 삽입 성능이 저하될 수 있습니다. 무작위 데이터를 대량으로 삽입하면 무작위 인덱스 항목이 생성되어 인덱스 크기가 늘어납니다. 인덱스가 다른 인덱스 항목에 액세스하기 위해 각 무작위 삽입이 필요한 크기에 도달하면 삽입으로 인해 WiredTiger 캐시 제거 및 교체 비율이 높아집니다. 이 경우 인덱스가 더 이상 캐시에 완전히 저장되지 않고 디스크에서 업데이트되어 성능이 저하됩니다.
인덱싱된 필드에 무작위 데이터를 대량 삽입하는 성능을 개선하려면 다음 두 가지 방법을 사용할 수 있습니다.
인덱스를 제거한 다음 임의의 데이터를 삽입한 후 다시 생성합니다.
데이터를 인덱싱되지 않은 빈 collection에 삽입합니다.
대량 삽입 후 인덱스를 생성하면 메모리의 데이터가 정렬되고 모든 인덱스에 대해 정렬된 삽입이 수행됩니다.
oplog 항목
db.collection.insertMany()
작업으로 하나 이상의 문서가 성공적으로 삽입되면 작업은 삽입된 각 문서마다 oplog(작업 로그)에 항목을 추가합니다. 작업이 실패하면 작업은 oplog에 항목을 추가하지 않습니다.
예시
다음 예시에서는 products
컬렉션에 문서를 삽입합니다.
_id
필드를 지정하지 않고 여러 문서 삽입
다음 예시에서는 db.collection.insertMany()
를 사용하여 _id
필드를 포함하지 않는 문서를 삽입합니다.
try { db.products.insertMany( [ { item: "card", qty: 15 }, { item: "envelope", qty: 20 }, { item: "stamps" , qty: 30 } ] ); } catch (e) { print (e); }
연산은 다음 문서를 반환합니다.
{ "acknowledged" : true, "insertedIds" : [ ObjectId("562a94d381cb9f1cd6eb0e1a"), ObjectId("562a94d381cb9f1cd6eb0e1b"), ObjectId("562a94d381cb9f1cd6eb0e1c") ] }
문서에 _id
가 포함되어 있지 않으므로 mongod
는 각 문서에 대해 _id
필드를 만들어 추가하고 이에 고유한 ObjectId()
값을 할당합니다.
ObjectId
값은 작업이 실행되는 기기 및 시간에 따라 다릅니다. 따라서 사용자의 값은 예시의 값과 다를 수 있습니다.
_id
필드를 지정하는 여러 문서 삽입
다음 예시/작업에서는 insertMany()
를 사용하여 _id
필드가 포함된 문서를 삽입합니다. 중복 키 오류를 방지하려면 _id
값이 컬렉션 내에서 고유해야 합니다.
try { db.products.insertMany( [ { _id: 10, item: "large box", qty: 20 }, { _id: 11, item: "small box", qty: 55 }, { _id: 12, item: "medium box", qty: 30 } ] ); } catch (e) { print (e); }
연산은 다음 문서를 반환합니다.
{ "acknowledged" : true, "insertedIds" : [ 10, 11, 12 ] }
_id
와 같이 고유 인덱스의 일부인 키에 중복 값을 삽입하면 예외가 발생합니다. 다음 작업에서는 이미 존재하는 _id
값을 가진 문서를 삽입하려고 시도합니다.
try { db.products.insertMany( [ { _id: 13, item: "envelopes", qty: 60 }, { _id: 13, item: "stamps", qty: 110 }, { _id: 14, item: "packing tape", qty: 38 } ] ); } catch (e) { print (e); }
_id: 13
이(가) 이미 존재하므로 다음 예외가 발생합니다.
BulkWriteError({ "writeErrors" : [ { "index" : 0, "code" : 11000, "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 13.0 }", "op" : { "_id" : 13, "item" : "stamps", "qty" : 110 } } ], "writeConcernErrors" : [ ], "nInserted" : 1, "nUpserted" : 0, "nMatched" : 0, "nModified" : 0, "nRemoved" : 0, "upserted" : [ ] })
하나의 문서가 삽입되었습니다. _id: 13
의 첫 번째 문서는 성공적으로 삽입되지만 두 번째 삽입은 실패합니다. 이렇게 하면 대기열에 남아 있는 추가 문서도 삽입되지 않습니다.
ordered
을(를) 사용하여 false
을(를) 지정하면 나머지 문서에 대한 삽입 연산이 계속됩니다.
순서가 지정되지 않은 삽입
다음은 _id
필드와 ordered: false
로 여러 문서를 삽입하려고 시도합니다. 문서 배열에는 _id
필드가 중복된 두 개의 문서가 포함되어 있습니다.
try { db.products.insertMany( [ { _id: 10, item: "large box", qty: 20 }, { _id: 11, item: "small box", qty: 55 }, { _id: 11, item: "medium box", qty: 30 }, { _id: 12, item: "envelope", qty: 100}, { _id: 13, item: "stamps", qty: 125 }, { _id: 13, item: "tape", qty: 20}, { _id: 14, item: "bubble wrap", qty: 30} ], { ordered: false } ); } catch (e) { print (e); }
이 작업에서는 다음과 같은 예외가 발생합니다.
BulkWriteError({ "writeErrors" : [ { "index" : 2, "code" : 11000, "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 11.0 }", "op" : { "_id" : 11, "item" : "medium box", "qty" : 30 } }, { "index" : 5, "code" : 11000, "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 13.0 }", "op" : { "_id" : 13, "item" : "tape", "qty" : 20 } } ], "writeConcernErrors" : [ ], "nInserted" : 5, "nUpserted" : 0, "nMatched" : 0, "nModified" : 0, "nRemoved" : 0, "upserted" : [ ] })
item: "medium box"
및 item: "tape"
이(가) 있는 문서는 _id
값이 중복되어 삽입되지 못했습니다. 그러나 nInserted
은(는) 나머지 문서 5개가 삽입되었음을 나타냅니다.
쓰기 고려 사용하기
3명으로 구성된 멤버 복제본 세트가 있는 경우 다음 작업은 majority
의 w
및 100
의 wtimeout
을 지정합니다.
try { db.products.insertMany( [ { _id: 10, item: "large box", qty: 20 }, { _id: 11, item: "small box", qty: 55 }, { _id: 12, item: "medium box", qty: 30 } ], { w: "majority", wtimeout: 100 } ); } catch (e) { print (e); }
기본 및 하나 이상의 보조 서버가 100밀리초 이내에 각 쓰기 작업을 확인하면 다음을 반환합니다.
{ "acknowledged" : true, "insertedIds" : [ ObjectId("562a94d381cb9f1cd6eb0e1a"), ObjectId("562a94d381cb9f1cd6eb0e1b"), ObjectId("562a94d381cb9f1cd6eb0e1c") ] }
복제본 세트의 모든 필수 노드가 쓰기 작업을 확인하는 데 필요한 총 시간이 wtimeout
이상인 경우 wtimeout
기간이 경과하면 다음 writeConcernError
가 표시됩니다.
이 연산은 다음을 반환합니다.
WriteConcernError({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })