The meaning of embedding a Document in MongoDB is different compared to column based stores. Typically the term is used for a Document in Document approach and not for flattening out a values into the enclosing Document.
Closes: #3600
Original pull request: #3604.
pull/3611/head
Christoph Strobl5 years agocommitted byMark Paluch
Embedded entities are used to design value objects in your Java domain model whose properties are flattened out into the parent's MongoDB Document.
Unwrapped entities are used to design value objects in your Java domain model whose properties are flattened out into the parent's MongoDB Document.
[[embedded-entities.mapping]]
[[unwrapped-entities.mapping]]
=== Embedded Types Mapping
=== Unwrapped Types Mapping
Consider the following domain model where `User.name` is annotated with `@Embedded`.
Consider the following domain model where `User.name` is annotated with `@Unwrapped`.
The `@Embedded` annotation signals that all properties of `UserName` should be unwrapped into the `user` document that owns the `name` property.
The `@Unwrapped` annotation signals that all properties of `UserName` should be flattened out into the `user` document that owns the `name` property.
.Sample Code of embedding objects
.Sample Code of unwrapping objects
====
====
[source,java]
[source,java]
----
----
@ -18,7 +18,7 @@ class User {
@Id
@Id
String userId;
String userId;
@Embedded(onEmpty = USE_NULL) <1>
@Unwrapped(onEmpty = USE_NULL) <1>
UserName name;
UserName name;
}
}
@ -43,23 +43,23 @@ class UserName {
By using `onEmpty=USE_EMPTY` an empty `UserName`, with potential `null` value for its properties, will be created.
By using `onEmpty=USE_EMPTY` an empty `UserName`, with potential `null` value for its properties, will be created.
====
====
For less verbose embeddable type declarations use `@Embedded.Nullable` and `@Embedded.Empty` instead `@Embedded(onEmpty = USE_NULL)` and `@Embedded(onEmpty = USE_EMPTY)`.
For less verbose embeddable type declarations use `@Unwrapped.Nullable` and `@Unwrapped.Empty` instead `@Unwrapped(onEmpty = USE_NULL)` and `@Unwrapped(onEmpty = USE_EMPTY)`.
Both annotations are meta-annotated with JSR-305 `@javax.annotation.Nonnull` to aid with nullability inspections.
Both annotations are meta-annotated with JSR-305 `@javax.annotation.Nonnull` to aid with nullability inspections.
[WARNING]
[WARNING]
====
====
It is possible to use complex types within an embedded object.
It is possible to use complex types within an unwrapped object.
However, those must not be, nor contain embedded fields themselves.
However, those must not be, nor contain unwrapped fields themselves.
====
====
[[embedded-entities.mapping.field-names]]
[[unwrapped-entities.mapping.field-names]]
=== Embedded Types field names
=== Unwrapped Types field names
A value object can be embedded multiple times by using the optional `prefix` attribute of the `@Embedded` annotation.
A value object can be unwrapped multiple times by using the optional `prefix` attribute of the `@Unwrapped` annotation.
By dosing so the chosen prefix is prepended to each property or `@Field("…")` name in the embedded object.
By dosing so the chosen prefix is prepended to each property or `@Field("…")` name in the unwrapped object.
Please note that values will overwrite each other if multiple properties render to the same field name.
Please note that values will overwrite each other if multiple properties render to the same field name.
.Sample Code of embedded object with name prefix
.Sample Code of unwrapped object with name prefix
====
====
[source,java]
[source,java]
----
----
@ -68,10 +68,10 @@ class User {
@Id
@Id
String userId;
String userId;
@Embedded.Nullable(prefix = "u_") <1>
@Unwrapped.Nullable(prefix = "u_") <1>
UserName name;
UserName name;
@Embedded.Nullable(prefix = "a_") <2>
@Unwrapped.Nullable(prefix = "a_") <2>
UserName name;
UserName name;
}
}
@ -97,10 +97,10 @@ class UserName {
<2> All properties of `UserName` are prefixed with `a_`.
<2> All properties of `UserName` are prefixed with `a_`.
====
====
While combining the `@Field` annotation with `@Embedded` on the very same property does not make sense and therefore leads to an error.
While combining the `@Field` annotation with `@Unwrapped` on the very same property does not make sense and therefore leads to an error.
It is a totally valid approach to use `@Field` on any of the embedded types properties.
It is a totally valid approach to use `@Field` on any of the unwrapped types properties.
.Sample Code embedded object with `@Field` annotation
.Sample Code unwrapping objects with `@Field` annotation
====
====
[source,java]
[source,java]
----
----
@ -109,7 +109,7 @@ public class User {
@Id
@Id
private String userId;
private String userId;
@Embedded.Nullable(prefix = "u-") <1>
@Unwrapped.Nullable(prefix = "u-") <1>
UserName name;
UserName name;
}
}
@ -132,17 +132,17 @@ public class UserName {
}
}
----
----
<1> All properties of `UserName` are prefixed with `u-`.
<1> All properties of `UserName` are prefixed with `u-`.
<2> Final field names are a result of concatenating `@Embedded(prefix)` and `@Field(name)`.
<2> Final field names are a result of concatenating `@Unwrapped(prefix)` and `@Field(name)`.
====
====
[[embedded-entities.queries]]
[[unwrapped-entities.queries]]
=== Query on Embedded Objects
=== Query on Unwrapped Objects
Defining queries on embedded properties is possible on type- as well as field-level as the provided `Criteria` is matched against the domain type.
Defining queries on unwrapped properties is possible on type- as well as field-level as the provided `Criteria` is matched against the domain type.
Prefixes and potential custom field names will be considered when rendering the actual query.
Prefixes and potential custom field names will be considered when rendering the actual query.
Use the property name of the embedded object to match against all contained fields as shown in the sample below.
Use the property name of the unwrapped object to match against all contained fields as shown in the sample below.
.Query on embedded object
.Query on unwrapped object
====
====
[source,java]
[source,java]
----
----
@ -160,9 +160,9 @@ db.collection.find({
----
----
====
====
It is also possible to address any field of the embedded object directly using its property name as shown in the snippet below.
It is also possible to address any field of the unwrapped object directly using its property name as shown in the snippet below.
.Query on field of embedded object
.Query on field of unwrapped object
====
====
[source,java]
[source,java]
----
----
@ -178,12 +178,12 @@ db.collection.find({
----
----
====
====
[[embedded-entities.queries.sort]]
[[unwrapped-entities.queries.sort]]
==== Sort by embedded field.
==== Sort by unwrapped field.
Fields of embedded objects can be used for sorting via their property path as shown in the sample below.
Fields of unwrapped objects can be used for sorting via their property path as shown in the sample below.
.Sort on embedded field
.Sort on unwrapped field
====
====
[source,java]
[source,java]
----
----
@ -201,15 +201,15 @@ db.collection.find({
[NOTE]
[NOTE]
====
====
Though possible, using the embedded object itself as sort criteria includes all of its fields in unpredictable order and may result in inaccurate ordering.
Though possible, using the unwrapped object itself as sort criteria includes all of its fields in unpredictable order and may result in inaccurate ordering.
====
====
[[embedded-entities.queries.project]]
[[unwrapped-entities.queries.project]]
==== Field projection on embedded objects
==== Field projection on unwrapped objects
Fields of embedded objects can be subject for projection either as a whole or via single fields as shown in the samples below.
Fields of unwrapped objects can be subject for projection either as a whole or via single fields as shown in the samples below.
.Project on embedded object.
.Project on unwrapped object.
====
====
[source,java]
[source,java]
----
----
@ -228,10 +228,10 @@ db.collection.find({
"lastname" : 1
"lastname" : 1
})
})
----
----
<1> A field projection on an embedded object includes all of its properties.
<1> A field projection on an unwrapped object includes all of its properties.
====
====
.Project on a field of an embedded object.
.Project on a field of an unwrapped object.
====
====
[source,java]
[source,java]
----
----
@ -249,21 +249,21 @@ db.collection.find({
"firstname" : 1
"firstname" : 1
})
})
----
----
<1> A field projection on an embedded object includes all of its properties.
<1> A field projection on an unwrapped object includes all of its properties.
====
====
[[embedded-entities.queries.by-example]]
[[unwrapped-entities.queries.by-example]]
==== Query By Example on embedded object.
==== Query By Example on unwrapped object.
Embedded objects can be used within an `Example` probe just as any other type.
Unwrapped objects can be used within an `Example` probe just as any other type.
Please review the <<query-by-example.running,Query By Example>> section, to learn more about this feature.
Please review the <<query-by-example.running,Query By Example>> section, to learn more about this feature.
[[embedded-entities.queries.repository]]
[[unwrapped-entities.queries.repository]]
==== Repository Queries on embedded objects.
==== Repository Queries on unwrapped objects.
The `Repository` abstraction allows deriving queries on fields of embedded objects as well as the entire object.
The `Repository` abstraction allows deriving queries on fields of unwrapped objects as well as the entire object.
Christoph Strobl
5 years ago
committed by
Mark Paluch