diff --git a/src/main/asciidoc/reference/mongodb.adoc b/src/main/asciidoc/reference/mongodb.adoc index 9f8861d3b..1f08d4452 100644 --- a/src/main/asciidoc/reference/mongodb.adoc +++ b/src/main/asciidoc/reference/mongodb.adoc @@ -1904,8 +1904,6 @@ AggregationResults results = template.aggregate(aggregation, "tags", T WARNING: Indexes are only used if the collation used for the operation matches the index collation. -include::./mongo-json-schema.adoc[leveloffset=+1] - <> support `Collations` via the `collation` attribute of the `@Query` annotation. .Collation support for Repositories @@ -1946,186 +1944,7 @@ as shown in (1) and (2), will be included when creating the index. TIP: The most specifc `Collation` outroules potentially defined others. Which means Method argument over query method annotation over doamin type annotation. ==== -[[mongo.jsonSchema]] -=== JSON Schema - -As of version 3.6, MongoDB supports collections that validate documents against a provided https://docs.mongodb.com/manual/core/schema-validation/#json-schema[JSON Schema]. -The schema itself and both validation action and level can be defined when creating the collection, as the following example shows: - -.Sample JSON schema -==== -[source,json] ----- -{ - "type": "object", <1> - - "required": [ "firstname", "lastname" ], <2> - - "properties": { <3> - - "firstname": { <4> - "type": "string", - "enum": [ "luke", "han" ] - }, - "address": { <5> - "type": "object", - "properties": { - "postCode": { "type": "string", "minLength": 4, "maxLength": 5 } - } - } - } -} ----- -<1> JSON schema documents always describe a whole document from its root. A schema is a schema object itself that can contain -embedded schema objects that describe properties and subdocuments. -<2> `required` is a property that describes which properties are required in a document. It can be specified optionally, along with other -schema constraints. See MongoDB's documentation on https://docs.mongodb.com/manual/reference/operator/query/jsonSchema/#available-keywords[available keywords]. -<3> `properties` is related to a schema object that describes an `object` type. It contains property-specific schema constraints. -<4> `firstname` specifies constraints for the `firsname` field inside the document. Here, it is a string-based `properties` element declaring - possible field values. -<5> `address` is a subdocument defining a schema for values in its `postCode` field. -==== - -You can provide a schema either by specifying a schema document (that is, by using the `Document` API to parse or build a document object) or by building it with Spring Data's JSON schema utilities in `org.springframework.data.mongodb.core.schema`. `MongoJsonSchema` is the entry point for all JSON schema-related operations. The following example shows how use `MongoJsonSchema.builder()` to create a JSON schema: - -.Creating a JSON schema -==== -[source,java] ----- -MongoJsonSchema.builder() <1> - .required("firstname", "lastname") <2> - - .properties( - string("firstname").possibleValues("luke", "han"), <3> - - object("address") - .properties(string("postCode").minLength(4).maxLength(5))) - - .build(); <4> ----- -<1> Obtain a schema builder to configure the schema with a fluent API. -<2> Configure required properties. -<3> Configure the String-typed `firstname` field, allowing only `luke` and `han` values. Properties can be typed or untyped. Use a static import of `JsonSchemaProperty` to make the syntax slightly more compact and to get entry points such as `string(…)`. -<4> Build the schema object. Use the schema to create either a collection or <>. -==== - -There are already some predefined and strongly typed schema objects (`JsonSchemaObject` and `JsonSchemaProperty`) available -through static methods on the gateway interfaces. -However, you may need to build custom property validation rules, which can be created through the builder API, as the following example shows: - -[source,java] ----- -// "birthdate" : { "bsonType": "date" } -JsonSchemaProperty.named("birthdate").ofType(Type.dateType()); - -// "birthdate" : { "bsonType": "date", "description", "Must be a date" } -JsonSchemaProperty.named("birthdate").with(JsonSchemaObject.of(Type.dateType()).description("Must be a date")); ----- - -The Schema builder also provides support for https://docs.mongodb.com/manual/core/security-client-side-encryption/[Client-Side Field Level Encryption]. Please refer to <> for more information, - -`CollectionOptions` provides the entry point to schema support for collections, as the following example shows: - -.Create collection with `$jsonSchema` -==== -[source,java] ----- -MongoJsonSchema schema = MongoJsonSchema.builder().required("firstname", "lastname").build(); - -template.createCollection(Person.class, CollectionOptions.empty().schema(schema)); ----- -==== - -You can use a schema to query any collection for documents that match a given structure defined by a JSON schema, as the following example shows: - -.Query for Documents matching a `$jsonSchema` -==== -[source,java] ----- -MongoJsonSchema schema = MongoJsonSchema.builder().required("firstname", "lastname").build(); - -template.find(query(matchingDocumentStructure(schema)), Person.class); ----- -==== - -The following table shows the supported JSON schema types: - -[cols="3,1,6", options="header"] -.Supported JSON schema types -|=== -| Schema Type -| Java Type -| Schema Properties - -| `untyped` -| - -| `description`, generated `description`, `enum`, `allOf`, `anyOf`, `oneOf`, `not` - -| `object` -| `Object` -| `required`, `additionalProperties`, `properties`, `minProperties`, `maxProperties`, `patternProperties` - -| `array` -| any array except `byte[]` -| `uniqueItems`, `additionalItems`, `items`, `minItems`, `maxItems` - -| `string` -| `String` -| `minLength`, `maxLentgth`, `pattern` - -| `int` -| `int`, `Integer` -| `multipleOf`, `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum` - -| `long` -| `long`, `Long` -| `multipleOf`, `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum` - -| `double` -| `float`, `Float`, `double`, `Double` -| `multipleOf`, `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum` - -| `decimal` -| `BigDecimal` -| `multipleOf`, `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum` - -| `number` -| `Number` -| `multipleOf`, `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum` - -| `binData` -| `byte[]` -| (none) - -| `boolean` -| `boolean`, `Boolean` -| (none) - -| `null` -| `null` -| (none) - -| `objectId` -| `ObjectId` -| (none) - -| `date` -| `java.util.Date` -| (none) - -| `timestamp` -| `BsonTimestamp` -| (none) - -| `regex` -| `java.util.regex.Pattern` -| (none) - -|=== - -NOTE: `untyped` is a generic type that is inherited by all typed schema types. It provides all `untyped` schema properties to typed schema types. - -For more information, see https://docs.mongodb.com/manual/reference/operator/query/jsonSchema/#op._S_jsonSchema[$jsonSchema]. +include::./mongo-json-schema.adoc[leveloffset=+1] [[mongo.query.fluent-template-api]] === Fluent Template API