db.collection.insertOne()
정의
db.collection.insertOne()
중요
Mongo쉬 방법
이 페이지에서는
mongosh
메서드를 설명합니다. 이는 데이터베이스 명령 또는 Node.js와 같은 언어별 드라이버에 대한 설명서가 아닙니다.데이터베이스 명령에 대해서는
insert
명령을 참조하세요.MongoDB API 드라이버의 경우 언어별 MongoDB 드라이버 설명서를 참조하세요.
단일 문서를 컬렉션에 삽입합니다.
반환합니다: 다음이 포함된 문서입니다. 작업이 쓰기 고려와 함께 실행된 경우 부울
acknowledged
를true
로, 쓰기 고려가 비활성화된 경우false
로 반환합니다.삽입된 문서의
_id
값이 있는 필드insertedId
입니다.
호환성
다음 환경에서 호스팅되는 배포에 db.collection.insertOne()
사용할 수 있습니다.
MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스
MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전
구문
insertOne()
메서드의 형식은 다음과 같습니다.
db.collection.insertOne( <document>, { writeConcern: <document> } )
insertOne()
메서드는 다음 매개변수를 사용합니다.
매개 변수 | 유형 | 설명 |
---|---|---|
document | 문서 | 컬렉션에 삽입할 문서입니다. |
writeConcern | 문서 | 선택 사항. 쓰기 고려를 표현하는 문서입니다. 기본 쓰기 고려를 사용하려면 생략합니다. .. include:: /includes/extracts/transactions-operations-write-concern.rst |
동작
컬렉션 생성
컬렉션이 존재하지 않으면 insertOne()
메서드가 컬렉션을 생성합니다.
_id
필드
문서에 _id 필드가 지정되지 않은 경우 mongod
에서 _id
필드를 추가하고 삽입하기 전에 문서에 고유한 ObjectId()
를 할당합니다. 대부분의 드라이버는 객체 ID를 생성하고 _id
필드를 삽입하지만, 드라이버나 애플리케이션이 수행하지 않는 경우 mongod
에서 _id
를 생성하여 채웁니다.
문서에 _id
필드가 포함된 경우 중복 키 오류를 방지하려면 _id
값이 컬렉션 내에서 고유해야 합니다.
설명 가능성
insertOne()
는 db.collection.explain()
과 호환되지 않습니다.
오류 처리
오류가 발생하면 db.collection.insertOne()
은 writeError
또는 writeConcernError
예외를 발생시킵니다.
스키마 유효성 검사 오류
컬렉션에서 스키마 유효성 검사 를 사용하고 validationAction
이(가) error
(으)로 설정된 경우 잘못된 문서를 삽입하면 MongoServerError
이(가) 발생하고 db.collection.insertOne()
이(가) 실패합니다.
트랜잭션
db.collection.insertOne()
는 분산 트랜잭션 내에서 사용할 수 있습니다.
중요
대부분의 경우 분산 트랜잭션은 단일 문서 쓰기에 비해 더 큰 성능 비용이 발생하므로 분산 트랜잭션의 가용성이 효과적인 스키마 설계를 대체할 수는 없습니다. 대부분의 시나리오에서 비정규화된 데이터 모델 (내장된 문서 및 배열) 은 계속해서 데이터 및 사용 사례에 최적일 것입니다. 즉, 대부분의 시나리오에서 데이터를 적절하게 모델링하면 분산 트랜잭션의 필요성이 최소화됩니다.
추가 트랜잭션 사용 고려 사항(예: 런타임 제한 및 oplog 크기 제한)은 프로덕션 고려사항을 참조하세요.
트랜잭션에서 컬렉션 생성
트랜잭션이 교차 샤드 쓰기 트랜잭션인 이 아닌 경우 분산 트랜잭션 내에서 컬렉션과 인덱스를 생성할 수 있습니다.
트랜잭션에서 존재하지 않는 컬렉션에 대한 삽입을 지정하면 MongoDB는 해당 컬렉션을 암시적으로 생성합니다.
쓰기 고려 및 트랜잭션
트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요.
oplog 항목
db.collection.insertOne()
작업으로 문서가 성공적으로 삽입되면 작업은 oplog(작업 로그)에 항목을 추가합니다. 작업이 실패하면 작업은 oplog에 항목을 추가하지 않습니다.
예제
필드를 지정하지 않고 문서 삽입 _id
다음 예시에서는 insertOne()
메서드로 전달된 문서에 _id
필드가 포함되어 있지 않습니다.
try { db.products.insertOne( { item: "card", qty: 15 } ); } catch (e) { print (e); };
연산은 다음 문서를 반환합니다.
{ "acknowledged" : true, "insertedId" : ObjectId("56fc40f9d735c28df206d078") }
문서에 _id
가 포함되어 있지 않으므로 mongod
는 _id
필드를 만들어 추가하고 고유한 ObjectId()
값을 할당합니다.
ObjectId
값은 작업이 실행되는 기기 및 시간에 따라 다릅니다. 따라서 사용자의 값은 예제의 값과 다를 수 있습니다.
필드를 지정하는 문서 삽입 _id
다음 예시에서는 insertOne()
메서드로 전달된 문서에 _id
필드가 포함되어 있습니다. 중복 키 오류를 방지하려면 _id
값이 컬렉션 내에서 고유해야 합니다.
try { db.products.insertOne( { _id: 10, item: "box", qty: 20 } ); } catch (e) { print (e); }
이 연산은 다음을 반환합니다:
{ "acknowledged" : true, "insertedId" : 10 }
_id
와 같이 고유 인덱스의 일부인 키에 중복 값을 삽입하면 예외가 발생합니다. 다음은 이미 존재하는 _id
값을 가진 문서를 삽입하려고 시도합니다.
try { db.products.insertOne( { _id: 10, "item" : "packing peanuts", "qty" : 200 } ); } catch (e) { print (e); }
_id: 10
이(가) 이미 존재하므로 다음 예외가 발생합니다.
WriteError({ "index" : 0, "code" : 11000, "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 10.0 }", "op" : { "_id" : 10, "item" : "packing peanuts", "qty" : 200 } })
쓰기 고려 증가
3명으로 구성된 멤버 복제본 세트가 있는 경우 다음 작업은 majority
의 w
및 100
의 wtimeout
을 지정합니다.
try { db.products.insertOne( { "item": "envelopes", "qty": 100, type: "Self-Sealing" }, { writeConcern: { 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" } } })