문서 홈 → 애플리케이션 개발 → MongoDB 매뉴얼
JSON 스키마 유효성 검사 지정
JSON 스키마는 JSON 문서에 주석을 달고 유효성을 검사할 수 있는 어휘입니다. JSON 스키마를 사용하여 사람이 읽을 수 있는 형식으로 필드에 대한 유효성 검사 규칙을 지정할 수 있습니다.
호환성
다음 환경에서 호스팅되는 배포에 JSON 스키마 유효성 검사를 사용할 수 있습니다.
MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스
MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전
컨텍스트
MongoDB는 4 핵심 사양 을 포함하여 JSON Schema의 초안 를 지원합니다. 및 유효성 검사 사양, 몇 가지 차이점이 있습니다. 자세한 내용은 확장 및 생략을 참조하세요.
JSON Schema에 대한 자세한 내용은 공식 웹사이트를 참조하세요.
제한 사항
다음의 스키마 유효성 검사를 지정할 수 없습니다:
admin
,local
,config
데이터베이스 컬렉션
컬렉션에서 클라이언트 측 필드 레벨 암호화 또는 Queryable Encryption 을 활성화한 경우 유효성 검사에는 다음과 같은 제한 사항이 적용됩니다.
CSFLE의 경우
collMod
실행할 때 libmongocrypt 라이브러리는 명령에 지정된 JSON 암호화 스키마 를 선호합니다. 이렇게 하면 아직 스키마가 없는 컬렉션에 스키마를 설정할 수 있습니다.Queryable Encryption의 경우, 암호화된 필드를 포함하는 JSON 스키마는 쿼리 분석 오류를 발생시킵니다.
단계
이 예에서는 students
유효성 검사 규칙이 있는 컬렉션을 만들고 유효하지 않은 문서를 삽입하려고 시도한 후 결과를 관찰합니다.
MongoDB 배포에 연결합니다.
mongosh
를 사용하여 로컬 MongoDB 인스턴스 또는 MongoDB Atlas 배포서버에 연결하려면 배포 서버에 연결 또는 mongosh를 통해 연결하기의 단계를 참조하세요.
유효성 검사를 사용하는 컬렉션을 생성합니다.
mongosh
에서 다음 명령을 실행하여 students
컬렉션을 만들고 $jsonSchema
연산자를 사용하여 스키마 유효성 검사 규칙을 설정합니다.
db.createCollection("students", { validator: { $jsonSchema: { bsonType: "object", title: "Student Object Validation", required: [ "address", "major", "name", "year" ], properties: { name: { bsonType: "string", description: "'name' must be a string and is required" }, year: { bsonType: "int", minimum: 2017, maximum: 3017, description: "'year' must be an integer in [ 2017, 3017 ] and is required" }, gpa: { bsonType: [ "double" ], description: "'gpa' must be a double if the field exists" } } } } } )
팁
제목 및 설명 필드로 규칙 명확히 하기
규칙이 명확하지 않은 경우 title
및 description
필드를 사용하여 유효성 검사 규칙에 대한 설명을 제공할 수 있습니다. 문서가 유효성 검사에 실패하면 MongoDB는 오류 출력에 이러한 필드를 포함합니다.
유효성 검사를 통해 유효하지 않은 문서를 방지하는지 확인합니다.
다음 명령을 실행합니다. 삽입 작업이 실패하는 이유는 gpa
필드가 정수형태인데, validator
가 이 필드를 double
형태로 요구하기 때문입니다.
db.students.insertOne( { name: "Alice", year: Int32( 2019 ), major: "History", gpa: Int32(3), address: { city: "NYC", street: "33rd Street" } } )
MongoServerError: Document failed validation Additional information: { failingDocumentId: ObjectId("630d093a931191850b40d0a9"), details: { operatorName: '$jsonSchema', title: 'Student Object Validation', schemaRulesNotSatisfied: [ { operatorName: 'properties', propertiesNotSatisfied: [ { propertyName: 'gpa', description: "'gpa' must be a double if the field exists", details: [ { operatorName: 'bsonType', specifiedAs: { bsonType: [ 'double' ] }, reason: 'type did not match', consideredValue: 3, consideredType: 'int' } ] } ] } ] } }
유효한 문서를 쿼리합니다.
문서가 성공적으로 삽입되었는지 확인하려면 다음 명령을 실행하여 students
컬렉션을 쿼리합니다.
db.students.find()
[ { _id: ObjectId("62bb413014b92d148400f7a5"), name: 'Alice', year: 2019, major: 'History', gpa: 3, address: { city: 'NYC', street: '33rd Street' } } ]
팁
Atlas 배포서버에 연결되어 있는 경우 Atlas UI에서 문서를 보고 필터링할 수도 있습니다.
추가 정보
JSON 스키마 유효성 검사와 쿼리 연산자 유효성검사를 결합할 수 있습니다.
예를 들어 이 스키마 유효성 검사를 사용하는 sales
컬렉션을 생각해 보겠습니다.
db.createCollection("sales", { validator: { "$and": [ // Validation with query operators { "$expr": { "$lt": ["$lineItems.discountedPrice", "$lineItems.price"] } }, // Validation with JSON Schema { "$jsonSchema": { "properties": { "items": { "bsonType": "array" } } } } ] } } )
sales
컬렉션의 문서에 대해 다음과 같은 규칙을 적용하는 유효성 검사가 이루어집니다:
lineItems.discountedPrice
lineItems.price
보다 작아야 합니다. 이 규칙은$lt
연산자를 사용하여 지정됩니다.items
필드는 배열이어야 합니다. 이 규칙은$jsonSchema
를 사용하여 지정됩니다.
자세히 알아보기
JSON 스키마에서 허용되는 키워드의 전체 목록을 보려면 사용 가능한 키워드를 참조하세요.
특정 필드에 포함할 수 있는 값을 제한하려면 허용된 필드 값 지정을 참조하세요.
JSON 스키마 유효성 검사 관련 문제를 방지하려면 JSON 스키마 유효성 검사를 위한 팁을 참조하세요.