스키마 유효성 검사
버전 3.2에 새로 추가되었습니다.
MongoDB는 업데이트 및 삽입 중에 스키마 유효성 검사를 수행할 수 있는 기능을 제공합니다.
MongoDB Atlas에서 호스팅되는 배포에 대해 UI에서 스키마 유효성 검사를 구현할수 있습니다.
유효성 검사 규칙 지정
유효성 검사 규칙은 컬렉션별로 적용됩니다.
새 컬렉션 을 만들 때 유효성 검사 규칙을 지정하려면 validator 옵션과 함께 db.createCollection() 를 사용합니다.
기존 컬렉션에 문서 유효성 검사를 추가하려면 collMod 명령을 validator 옵션과 함께 사용합니다.
MongoDB는 다음과 같은 관련 옵션도 제공합니다.
validationLevel옵션은 MongoDB가 업데이트 중에 기존 문서에 유효성 검사 규칙을 얼마나 엄격하게 적용하는지 결정합니다.validationAction옵션은 MongoDB가 유효성 검사 규칙을 위반하는 문서를error하고 거부할지, 아니면 로그에서 위반에 대해warn을 표시하지만 유효하지 않은 문서를 허용할지를 결정합니다.
JSON Schema
버전 3.6에 새로 추가되었습니다.
버전 3.6 부터 MongoDB 는 JSON schema 유효성 검사를 지원합니다. JSON schema 유효성 검사를 지정하려면 validator 표현식에 $jsonSchema 연산자를 사용합니다.
참고
JSON schema 는 스키마 유효성 검사를 수행하는 데 권장되는 수단입니다.
예를 들어 다음 예제에서는 JSON schema를 사용하여 유효성 검사 규칙을 지정합니다.
db.createCollection("students", { validator: { $jsonSchema: { bsonType: "object", required: [ "name", "year", "major", "address" ], properties: { name: { bsonType: "string", description: "must be a string and is required" }, year: { bsonType: "int", minimum: 2017, maximum: 3017, description: "must be an integer in [ 2017, 3017 ] and is required" }, major: { enum: [ "Math", "English", "Computer Science", "History", null ], description: "can only be one of the enum values and is required" }, gpa: { bsonType: [ "double" ], description: "must be a double if the field exists" }, address: { bsonType: "object", required: [ "city" ], properties: { street: { bsonType: "string", description: "must be a string if the field exists" }, city: { bsonType: "string", description: "must be a string and is required" } } } } } } })
자세한 내용은 $jsonSchema를 참조하세요.
bsonType 정의는 BSON types 페이지에서 확인할 수 있습니다.
기타 쿼리 표현식
JSON schema $jsonSchema 쿼리 연산자를MongoDB 사용하는 유효성 검사 외에도 는 다음을 제외한 다른 쿼리 연산자 와의 유효성 검사를 지원합니다.
예를 들어 다음 예제에서는 쿼리 표현식을 사용하여 유효성 검사기 규칙을 지정합니다.
db.createCollection( "contacts", { validator: { $or: [ { phone: { $type: "string" } }, { email: { $regex: /@mongodb\.com$/ } }, { status: { $in: [ "Unknown", "Incomplete" ] } } ] } } )
행동
유효성 검사는 업데이트 및 삽입 중에 발생합니다. 컬렉션에 유효성 검사를 추가하면 기존 문서는 수정될 때까지 유효성 검사를 거치지 않습니다.
기존 문서에 대한 유효성 검사를 수행하려면 validate 명령 또는 db.collection.validate() shell 도우미를 사용합니다.
기존 문서
validationLevel 옵션은 MongoDB가 유효성 검사 규칙을 적용하는 작업을 결정합니다.
validationLevel가strict(기본값)이면 MongoDB는 모든 삽입 및 업데이트에 유효성 검사 규칙을 적용합니다.validationLevel이moderate인 경우 MongoDB는 이미 유효성 검사 기준을 충족하는 기존 문서의 삽입 및 업데이트에 유효성 검사 규칙을 적용합니다.moderate수준에서는 유효성 검사 기준을 충족하지 않는 기존 문서에 대한 업데이트의 유효성이 확인되지 않습니다.
예를 들어, 다음 문서를 사용하여 contacts 컬렉션을 만듭니다.
db.contacts.insert([ { "_id": 1, "name": "Anne", "phone": "+1 555 123 456", "city": "London", "status": "Complete" }, { "_id": 2, "name": "Ivan", "city": "Vancouver" } ])
다음 명령을 실행하여 contacts 컬렉션에 유효성 검사기를 추가합니다.
db.runCommand( { collMod: "contacts", validator: { $jsonSchema: { bsonType: "object", required: [ "phone", "name" ], properties: { phone: { bsonType: "string", description: "must be a string and is required" }, name: { bsonType: "string", description: "must be a string and is required" } } } }, validationLevel: "moderate" } )
이제 contacts 컬렉션에 moderate validationLevel을 가진 유효성 검사기가 있습니다.
_id: 1(으)로 문서를 업데이트하려고 하면 기존 문서가 기준과 일치하므로 MongoDB는 새 유효성 검사 규칙을 적용합니다.반면 MongoDB는
_id: 2이(가) 유효성 검사 규칙을 충족하지 않는 문서의 업데이트에 유효성 검사 규칙을 적용하지 않습니다.
MongoDB 버전 5.0 부터 유효성 검사 조건이 충족되지 않을 때 유효성 검사기는 자세한 오류 정보를 반환합니다. 오류 출력은 포괄적이며 첫 번째 오류뿐만 아니라 모든 오류가 보고됩니다.
중요
오류 출력은 사람이 볼 수 있도록 만들어졌습니다. 향후 변경될 수 있으며 스크립트에 의존해서는 안 됩니다.
다음 예에서는 두 업데이트 모두 name 을 string 로 요구하는 위에서 만든 유효성 검사 규칙과 일치하지 않습니다.
db.contacts.update( { _id: 1 }, { $set: { name: 10 } } ) db.contacts.update( { _id: 2 }, { $set: { name: 20 } } )
아래 출력은 errInfo 객체에 표시된 대로 _id: 1 가 있는 문서가 유효성 검사에 실패했음을 보여 주는 자세한 설명과 함께 문서를 보여줍니다. 이 문서가 유효성 검사 추가 시 초기 기준을 충족하지 않았으므로 _id: 2 이 있는 문서에 대해 업데이트가 성공했습니다.
// _id: 1 WriteResult({ "nMatched" : 0, "nUpserted" : 0, "nModified" : 0, "writeError" : { "code" : 121, "errmsg" : "Document failed validation", "errInfo" : { "failingDocumentId" : 1, "details" : { "operatorName" : "$jsonSchema", "schemaRulesNotSatisfied" : [ { "operatorName" : "properties", "propertiesNotSatisfied" : [ { "propertyName" : "name", "details" : [ { "operatorName" : "bsonType", "specifiedAs" : { "bsonType" : "string" }, "reason" : "type did not match", "consideredValue" : 10, "consideredType" : "double" } ] } ] } ] } } } }) // _id: 2 WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })
유효성 검사를 완전히 비활성화하려면 validationLevel 을 off 로 설정할 수 있습니다.
유효하지 않은 문서 수락 또는 거부
validationAction 옵션은 MongoDB가 유효성 검사 규칙을 위반하는 문서를 처리하는 방법을 결정합니다.
validationAction가error(기본값)이면 MongoDB는 유효성 검사 기준을 위반하는 모든 삽입 또는 업데이트를 거부합니다.validationAction가warn인 경우 MongoDB는 모든 위반 사항을 기록하지만 삽입 또는 업데이트의 진행은 허용합니다.
예를 들어 다음 JSON schema 유효성 검사기를 사용하여 contacts2 컬렉션을 만듭니다.
db.createCollection( "contacts2", { validator: { $jsonSchema: { bsonType: "object", required: [ "phone" ], properties: { phone: { bsonType: "string", description: "must be a string and is required" }, email: { bsonType : "string", pattern : "@mongodb\.com$", description: "must be a string and match the regular expression pattern" }, status: { enum: [ "Unknown", "Incomplete" ], description: "can only be one of the enum values" } } } }, validationAction: "warn" } )
warn validationAction 를 사용하면 MongoDB는 모든 위반 사항을 기록하지만 삽입 또는 업데이트를 계속 진행할 수 있습니다.
예를 들어 다음 삽입 작업은 유효성 검사 규칙을 위반합니다.
db.contacts2.insertOne( { name: "Amanda", status: "Updated" } )
그러나 validationAction 는 warn 전용이므로 MongoDB는 유효성 검사 위반 메시지만 기록하고 작업 진행을 허용합니다. 다음 명령을 실행하여 MongoDB 로그를 확인합니다.
db.adminCommand( { getLog: "global" } )
컬렉션 사용량에 따라 이 명령은 많은 데이터를 반환할 수 있습니다. 유효성 검사 오류(로그에 긴 한 줄, 가독성을 위해 여기에 형식이 다시 지정됨)에는 다음과 같은 정보가 포함됩니다.
"{\"t\":{\"$date\":\"2021-01-20T15:59:57.305+00:00\"}, \"s\":\"W\", \"c\":\"STORAGE\", \"id\":20294, \"ctx\":\"conn1\", \"msg\":\"Document would fail validation\", \"attr\":{\"namespace\":\"test.contacts2\", \"document\":{\"_id\":{\"$oid\":\"6008537d42e0d23385568881\"}, \"name\":\"Amanda\", \"status\":\"Updated\"}, \"errInfo\":{\"failingDocumentId\":{\"$oid\":\"6008537d42e0d23385568881\"}, \"details\":{\"operatorName\":\"$jsonSchema\", \"schemaRulesNotSatisfied\":[ {\"operatorName\":\"properties\", \"propertiesNotSatisfied\":[ {\"propertyName\":\"status\", \"details\":[ {\"operatorName\":\"enum\", \"specifiedAs\":{\"enum\":[ \"Unknown\", \"Incomplete\"]}, \"reason\":\"value was not found in enum\", \"consideredValue\":\"Updated\"}]}]}, {\"operatorName\":\"required\", \"specifiedAs\":{\"required\":[\"phone\"]}, \"missingProperties\":[\"phone\"]}]}}}}"
제한 사항
admin, local 및 config 데이터베이스의 컬렉션에는 유효성 검사기를 지정할 수 없습니다.
system.* 컬렉션에 대한 유효성 검사기를 지정할 수 없습니다.
bypassDocumentValidation
사용자는 bypassDocumentValidation 옵션을 사용하여 문서 유효성 검사를 우회할 수 있습니다.
다음 명령은 새로운 옵션 bypassDocumentValidation 을 사용하여 작업별 유효성 검사를 우회할 수 있습니다.
applyOps명령mapReduce명령 및db.collection.mapReduce()메서드insert명령update명령aggregate명령 및db.collection.aggregate()메서드에 대한$out및$merge단계
액세스 제어를 활성화한 배포의 경우 문서 유효성 검사를 우회하려면 인증된 사용자에게 bypassDocumentValidation 작업이 있어야 합니다. 기본 제공 역할 dbAdmin 및 restore가 이 작업을 제공합니다.