JSON スキーマ検証の使用 - Amazon DocumentDB
JSON スキーマ検証の作成と使用サポートされるキーワードbypassDocumentValidation制限

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

JSON スキーマ検証の使用

$jsonSchema 評価クエリ演算子を使用すると、コレクションに挿入されているドキュメントを検証できます。

JSON スキーマ検証の作成と使用

スキーマ検証によるコレクションの作成

createCollection 操作ルールと検証ルールを含むコレクションを作成できます。これらの検証ルールは、Amazon DocumentDB ドキュメントの挿入または更新時に適用されます。以下は、従業員のコレクションの検証ルールを説明するコード例です。

db.createCollection("employees", {
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   },
   "validationLevel": "strict", "validationAction": "error"
} )

有効なドキュメントを挿入します

次の例では、上記のスキーマ検証ルールに準拠するドキュメントを挿入します。

db.employees.insert({"name" : { "firstName" : "Carol" , "lastName" : "Smith"}, "employeeId": "c720a" , "salary": 1000.0 })
db.employees.insert({ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24})

無効なドキュメントを挿入します

次の例では、上記のスキーマ検証ルールに準拠していないドキュメントを挿入します。この例では、employeeId の値は文字列ではありません。

db.employees.insert({
    "name" : { "firstName" : "Carol" , "lastName" : "Smith"}, 
    "employeeId": 720 , 
    "salary": 1000.0 
})

この例は、文書内の構文が正しくないことを示しています。

コレクションを変更する

collMod コマンドは、既存のコレクションの検証ルールを追加または変更するために使用されます。次の例では、給与フィールドを必須フィールドリストに追加しています。

db.runCommand({"collMod" : "employees", 
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId", "salary"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   }
} )

検証ルールが変更される前に追加されたドキュメントの対処

検証ルールが変更される前にコレクションに追加されたドキュメントの対処には、以下の validationLevel 修飾子を使用します。

  • strict: すべての挿入と更新に検証ルールを適用します。

  • moderate: 既存の有効なドキュメントに検証ルールを適用します。更新中、既存の無効なドキュメントはチェックされません。

次の例では、「employees」という名前のコレクションの検証ルールを更新した後に、給与フィールドが必須になります。次のドキュメントの更新は失敗します。

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }] 
})

Amazon DocumentDB は、次の出力を返します。

{
"n" : 0,
    "nModified" : 0,
    "writeErrors" : [
        {
"index" : 0,
            "code" : 121,
            "errmsg" : "Document failed validation"
        }
    ],
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

検証レベルを moderate に更新すると、上記のドキュメントを正常に更新できるようになります。

db.runCommand({
    "collMod" : "employees", 
    validationLevel : "moderate"
})

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }]
})

Amazon DocumentDB は、次の出力を返します。

{
"n" : 1,
    "nModified" : 1,
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

$jsonSchema を使用してドキュメントの取得

$jsonSchema 演算子は、JSON スキーマに一致するドキュメントをクエリするフィルタとして使用できます。これは最上位の演算子で、フィルタードキュメントに最上位フィールドとして含めることも $and、$or、$nor などのクエリ演算子と一緒に使用することもできます。以下の例は、$jsonSchema を個別のフィルターとして、また他のフィルター演算子と併用する方法を示しています。

「employee」コレクションに挿入されたドキュメント:

{ "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
{ "name" : { "firstName" : "Jane", "lastName" : "Doe" }, "employeeId" : "c721a", "salary" : 1300 }

$jsonSchema 演算子のみでフィルタリングされたコレクション:

db.employees.find({ 
       $jsonSchema: { required: ["age"] } })

Amazon DocumentDB は、次の出力を返します。

{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

$jsonSchema 演算子と別の演算子でフィルタリングされたコレクション:

db.employees.find({ 
       $or: [{ $jsonSchema: { required: ["age", "name"]}}, 
            { salary: { $lte:1000}}]});

Amazon DocumentDB は、次の出力を返します。

{ "_id" : ObjectId("64e5f8886218c620cf0e8f8a"), "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

$jsonSchema 演算子でフィルタリングされ、集計フィルタでは $match でフィルタリングされたコレクション:

db.employees.aggregate(
    [{ $match: { 
        $jsonSchema: { 
            required: ["name", "employeeId"],  
            properties: {"salary" :{"bsonType": "double"}}
        }
       }
    }]
)

Amazon DocumentDB は、次の出力を返します。

{ 
"_id" : ObjectId("64e5f8886218c620cf0e8f8a"),
 "name" : { "firstName" : "Carol", "lastName" : "Smith" },
"employeeId" : "c720a",
"salary" : 1000 
}
{
"_id" : ObjectId("64e5f91c6218c620cf0e8f8b"),
"name" : { "firstName" : "Emily", "lastName" : "Brown" },
"employeeId" : "c720b",
"age" : 25,
"salary" : 1050.2
}
{
"_id" : ObjectId("64e5f94e6218c620cf0e8f8c"),
"name" : { "firstName" : "William", "lastName" : "Taylor" },
"employeeId" : "c721a",
"age" : 24,
"salary" : 1400.5
}
{
"_id" : ObjectId("64e5f9786218c620cf0e8f8d"),
"name" : { "firstName" : "Jane", "lastName" : "Doe" },
"employeeId" : "c721a",
"salary" : 1300
}

既存の検証ルールの表示

コレクションの既存の検証ルールを確認するには、以下を使用してください。

db.runCommand({
    listCollections: 1, 
    filter: { name: 'employees' }
})

Amazon DocumentDB は、次の出力を返します。

{
    "waitedMS" : NumberLong(0),
    "cursor" : {
        "firstBatch" : [
            {
                "name" : "employees",
                "type" : "collection",
                "options" : {
                    "autoIndexId" : true,
                    "capped" : false,
                    "validator" : {
                        "$jsonSchema" : {
                            "bsonType" : "object",
                            "title" : "employee validation",
                            "required" : [
                                "name",
                                "employeeId",
                                "salary"
                            ],
                            "properties" : {
                                "name" : {
                                    "bsonType" : "object",
                                    "properties" : {
                                        "firstName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        },
                                        "lastName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        }
                                    },
                                    "additionalProperties" : false
                                },
                                "employeeId" : {
                                    "bsonType" : "string",
                                    "description" : "Unique Identifier for employee"
                                },
                                "salary" : {
                                    "bsonType" : "double"
                                },
                                "age" : {
                                    "bsonType" : "number"
                                }
                            },
                            "additionalProperties" : true
                        }
                    },
                    "validationLevel" : "moderate",
                    "validationAction" : "error"
                },
                "info" : {
                    "readOnly" : false
                },
                "idIndex" : {
                    "v" : 2,
                    "key" : {
                        "_id" : 1
                    },
                    "name" : "_id_",
                    "ns" : "test.employees"
                }
            }
        ],
        "id" : NumberLong(0),
        "ns" : "test.$cmd.listCollections"
    },
    "ok" : 1,
    "operationTime" : Timestamp(1692788937, 1)
}

Amazon DocumentDB は、$out 集約ステージでも検証ルールを保持します。

サポートされるキーワード

create および collMod コマンドでは以下のフィールドがサポートされています。

  • Validator: $jsonSchem オペレーションをサポートしています。

  • ValidationLevel: off、strict、moderate の値をサポートします。

  • ValidationAction: error の値をサポートします。

$jsonSchema 演算子は以下のキーワードをサポートします。

  • additionalItems

  • additionalProperties

  • allOf

  • anyOf

  • bsonType

  • dependencies

  • description

  • enum

  • exclusiveMaximum

  • exclusiveMinimum

  • items

  • maximum

  • minimum

  • maxItems

  • minItems

  • maxLength

  • minLength

  • maxProperties

  • minProperties

  • multipleOf

  • not

  • oneOf

  • pattern

  • patternProperties

  • properties

  • required

  • title

  • type

  • uniqueItems

bypassDocumentValidation

Amazon DocumentDB は、次のコマンドとメソッドについて bypassDocumentValidation をサポートしています。

  • insert

  • update

  • findAndModify

  • aggregate コマンドおよび db.collection.aggregate() メソッドにおける $out ステージ

Amazon DocumentDB は、次のコマンドについては bypassDocumentValidation をサポートしていません。

  • aggregate コマンドおよび db.collection.aggregate() メソッドにおける $merge

  • mapReduce コマンドおよび db.collection.mapReduce() メソッド

  • applyOps コマンド

制限

$jsonSchema の検証には以下の制限が適用されます。

  • Amazon DocumentDB は、オペレーションが検証ルールに失敗すると、「ドキュメントの検証に失敗しました」というエラーを返します。

  • Amazon DocumentDB Elastic クラスターは、$jsonSchema をサポートしていません。