문서 메뉴

문서 홈 → 애플리케이션 개발 → MongoDB 매뉴얼

db.collection.insertOne()

이 페이지의 내용

  • 정의
  • 호환성
  • 구문
  • 동작
  • 예제

정의

db.collection.insertOne()

중요

Mongo쉬 방법

이 페이지에서는 mongosh 메서드를 설명합니다. 이는 데이터베이스 명령이나 Node.js와 같은 언어별 드라이버에 대한 설명서가 아닙니다 .

데이터베이스 명령에 대해서는 insert 명령을 참조하십시오.

MongoDB API 드라이버의 경우 언어별 MongoDB 드라이버 설명서를 참조하세요.

레거시 mongo 셸 문서는 해당 MongoDB 서버 릴리스 문서를 참조하세요.

Mongo 셸 V4.4

단일 문서를 컬렉션에 삽입합니다.

반환합니다:다음이 포함된 문서입니다.

  • 작업이 쓰기 고려와 함께 실행된 경우 부울 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 예외를 발생시킵니다.

트랜잭션

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() →

이 페이지의 내용