insert
정의
insert
insert
명령은 하나 이상의 문서를 삽입하고 모든 삽입 상태가 포함된 문서를 반환합니다. MongoDB 드라이버에서 제공하는 삽입 메서드는 내부적으로 이 명령을 사용합니다.팁
mongosh
에서 이 명령은db.collection.insertOne()
및db.collection.insertMany()
도우미 메서드를 통해 실행할 수도 있습니다.헬퍼 메서드는
mongosh
사용자에게 편리하지만 데이터베이스 명령과 동일한 수준의 정보를 반환하지 못할 수 있습니다. 편의가 필요하지 않거나 추가 리턴 필드가 필요한 경우 데이터베이스 명령을 사용합니다.반환합니다: 작업 상태가 포함된 문서입니다. 자세한 내용은 출력을 참조하세요.
호환성
이 명령은 다음 환경에서 호스팅되는 배포에서 사용할 수 있습니다.
MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스
참고
이 명령은 모든 MongoDB Atlas 클러스터에서 지원됩니다. 모든 명령에 대한 Atlas 지원 에 대한 자세한 내용은 지원되지 않는 명령을 참조하세요.
MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전
구문
명령은 다음과 같은 구문을 가집니다:
db.runCommand( { insert: <collection>, documents: [ <document>, <document>, <document>, ... ], ordered: <boolean>, maxTimeMS: <integer>, writeConcern: { <write concern> }, bypassDocumentValidation: <boolean>, comment: <any> } )
명령 필드
이 명령은 다음 필드를 사용합니다.
필드 | 유형 | 설명 |
---|---|---|
insert | 문자열 | 대상 컬렉션의 이름입니다. |
documents | 배열 | 이름이 지정된 컬렉션에 삽입할 하나 이상의 문서 배열입니다. |
ordered | 부울 | 선택 사항입니다. true 인 경우 문서 삽입이 실패하면 inserts 배열에 나열된 나머지 문서를 삽입하지 않고 반환합니다. false 인 경우 문서 삽입에 실패하면 나머지 문서를 계속 삽입합니다. 기본값은 true 입니다. |
maxTimeMS | non-negative integer | 선택 사항. 시간 제한을 밀리초 단위로 지정합니다. MongoDB는 |
writeConcern | 문서 | 선택 사항. 트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요. |
bypassDocumentValidation | 부울 | 선택 사항입니다. 작업 중에 insert (이)가 문서 유효성 검사를 우회하도록 설정합니다. 이를 통해 유효성 검사 요구 사항을 충족하지 않는 문서를 삽입할 수 있습니다. |
comment | any | 선택 사항. 이 명령에 첨부할 사용자 제공 코멘트입니다. 설정되면 이 설명은 다음 위치에서 이 명령의 레코드와 함께 표시됩니다.
댓글은 유효한 모든 BSON types (문자열, 정수, 객체, 배열 등)이 될 수 있습니다. |
행동
크기 제한
모든 documents
배열 요소의 총 크기는 최대 BSON 문서 크기 이하여야 합니다.
documents
배열의 총 문서 수는 최대 대량 크기 이하여야 합니다.
문서 유효성 검사
insert
명령은 유효성 검사 규칙이 있는 컬렉션에 문서를 삽입하거나 업데이트할 때 문서 유효성 검사를 무시할 수 있는 bypassDocumentValidation
옵션에 대한 지원을 추가합니다.
트랜잭션
insert
는 분산 트랜잭션 내에서 사용할 수 있습니다.
중요
대부분의 경우 분산 트랜잭션은 단일 문서 쓰기에 비해 더 큰 성능 비용이 발생하므로 분산 트랜잭션의 가용성이 효과적인 스키마 설계를 대체할 수는 없습니다. 대부분의 시나리오에서 비정규화된 데이터 모델 (내장된 문서 및 배열) 은 계속해서 데이터 및 사용 사례에 최적일 것입니다. 즉, 대부분의 시나리오에서 데이터를 적절하게 모델링하면 분산 트랜잭션의 필요성이 최소화됩니다.
추가 트랜잭션 사용 고려 사항(예: 런타임 제한 및 oplog 크기 제한)은 프로덕션 고려사항을 참조하세요.
트랜잭션에서 컬렉션 생성
트랜잭션이 교차 샤드 쓰기 트랜잭션(write transaction)인 이 아닌 경우 분산 트랜잭션 내에서 컬렉션과 인덱스를 생성할 수 있습니다.
트랜잭션에서 존재하지 않는 컬렉션에 대한 삽입을 지정하면 MongoDB는 해당 컬렉션을 암시적으로 생성합니다.
쓰기 고려 및 트랜잭션
트랜잭션에서 실행되는 경우 작업에 대한 쓰기 고려를 명시적으로 설정하지 마세요. 트랜잭션에 쓰기 고려를 사용하려면 트랜잭션 및 쓰기 고려를 참조하세요.
부정확한 삽입
삽입 중에 서버 오류가 발생하더라도 일부 문서가 삽입되었을 수 있습니다.
삽입에 성공하면 시스템에서 컬렉션에 삽입된 문서 수 insert.n
을 반환합니다. 복제본 세트 상태 변경으로 인해 삽입 작업이 중단되면 시스템에서 문서 삽입을 계속할 수 있습니다. 따라서 insert.n
은 실제 삽입된 문서보다 적은 수의 문서를 보고할 수 있습니다.
예시
단일 문서 삽입
users
컬렉션에 문서를 삽입합니다.
db.runCommand( { insert: "users", documents: [ { _id: 1, user: "abc123", status: "A" } ] } )
반환된 문서는 명령이 문서를 성공적으로 삽입했음을 보여줍니다. 자세한 내용은 출력을 참조하세요.
{ "ok" : 1, "n" : 1 }
Bulk Insert
users
컬렉션에 문서 3개를 삽입합니다.
db.runCommand( { insert: "users", documents: [ { _id: 2, user: "ijk123", status: "A" }, { _id: 3, user: "xyz123", status: "P" }, { _id: 4, user: "mop123", status: "P" } ], ordered: false, writeConcern: { w: "majority", wtimeout: 5000 } } )
반환된 문서는 명령이 문서 세 개를 성공적으로 삽입했음을 보여줍니다. 자세한 내용은 출력을 참조하세요.
{ "ok" : 1, "n" : 3 }
삽입과 함께 사용 bypassDocumentValidation
스키마 유효성 검사 validationActions이 error
로 설정되는 경우 스키마 유효성 검사 규칙을 위반하는 문서에 대해 컬렉션에 삽입하면 오류가 반환됩니다. 이러한 규칙을 위반하는 문서를 삽입하려면 bypassDocumentValidation: true
를 설정합니다.
status
필드에 유효성 검사 규칙이 있는 user
컬렉션을 만듭니다.
유효성 검사 규칙은 상태가 'Unknown(알 수 없음)' 또는 'Incomplete(불완전)'인지 확인합니다.
db.createCollection("users", { validator: { status: { $in: [ "Unknown", "Incomplete" ] } } })
유효성 검사 규칙을 위반하는 문서를 삽입하려고 시도합니다.
db.runCommand({ insert: "users", documents: [ {user: "123", status: "Active" } ] })
삽입은 쓰기 오류 메시지를 반환합니다,
{ n: 0, writeErrors: [ { index: 0, code: 121, errInfo: { failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'), details: { operatorName: '$in', specifiedAs: { status: { '$in': [Array] } }, reason: 'no matching value found in array', consideredValue: 'Active' } }, errmsg: 'Document failed validation' } ], ok: 1 }
bypassDocumentValidation : true
를 설정하고 삽입을 다시 실행합니다.
db.runCommand({ insert: "users", documents: [ {user: "123", status: "Active" } ], bypassDocumentValidation: true })
작업이 성공합니다.
스키마 유효성 검사 규칙을 위반하는 문서를 확인하려면 validate
명령을 사용합니다.
출력
반환된 문서에는 다음 필드의 하위 집합이 포함되어 있습니다.
insert.writeErrors
삽입 작업 중에 발생한 오류에 관한 정보가 포함된 문서 배열입니다.
writeErrors
배열에는 오류가 발생한 각 삽입에 대한 오류 문서가 포함되어 있습니다.각 오류 문서에는 다음과 같은 필드가 포함되어 있습니다.
insert.writeConcernError
쓰기 고려 (write concern) 와 관련된 오류를 설명하는 문서입니다.
버전 7.1에서 변경됨:
insert
가mongos
에서 실행되면 하나 이상의 쓰기 오류가 발생하더라도 쓰기 고려 오류가 항상 보고됩니다.이전 릴리스에서는 쓰기 (write) 오류가 발생하면
insert
가 쓰기 고려 (write concern) 오류를 보고하지 않을 수 있었습니다.writeConcernError
문서에는 다음 필드가 포함되어 있습니다.insert.writeConcernError.errInfo.writeConcern
해당 작업에 사용되는 쓰기 관련 객체입니다. 쓰기 문제 객체 필드에 대한 자세한 내용은 쓰기 문제 사양을 참조하세요.
쓰기 고려 객체에는 쓰기 문제의 원본을 나타내는 다음 필드도 포함될 수 있습니다.
insert.writeConcernError.errInfo.writeConcern.provenance
쓰기 문제가 발생한 위치를 나타내는 문자열 값입니다(쓰기 문제
provenance
라고도 함). 다음 표에는 이 필드에 사용할 수 있는 값과 그 의미가 나와 있습니다.출처설명clientSupplied
쓰기 우려 사항은 애플리케이션에서 지정되었습니다.customDefault
쓰기 고려는 사용자 정의된 기본값에서 비롯된 것입니다.setDefaultRWConcern
을 참조하십시오.getLastErrorDefaults
쓰기 고려는 복제본 세트의settings.getLastErrorDefaults
필드에서 발생했습니다.implicitDefault
쓰기 고려는 다른 모든 쓰기 고려 사양이 없는 상태에서 서버에서 발생했습니다.
다음은 단일 문서의 성공적인 insert
에 대해 반환된 예시 문서입니다.
{ ok: 1, n: 1 }
다음은 insert
문서 두 개 중 하나는 성공적으로 삽입되었지만 다른 문서에서 오류가 발생한 경우 반환된 문서 예시입니다.
{ "ok" : 1, "n" : 1, "writeErrors" : [ { "index" : 1, "code" : 11000, "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_ dup key: { : 1.0 }" } ] }