문서 메뉴
문서 홈
/
MongoDB 매뉴얼
/
참조
/
Mongosh
/
컬렉션 메서드

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 배포를 위한 완전 관리형 서비스

구문

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"
     }
   }
})

팁

다음도 참조하세요.

돌아가기

db.collection.insert()

다음

db.collection.insertMany()

이 페이지의 내용