Update entity linking support to derive document pointer from lookup query.
Simplify usage by computing the pointer from the lookup. Update the reference documentation, add JavaDoc and refine API. Original pull request: #3647. Closes #3602.
This commit is contained in:
Christoph Strobl
committed by
Mark Paluch
Mark Paluch
parent
48ac7e75ba
commit
6ed274bd9b
@@ -1,6 +1,11 @@
|
||||
[[new-features]]
|
||||
= New & Noteworthy
|
||||
|
||||
[[new-features.3.3]]
|
||||
== What's New in Spring Data MongoDB 3.3
|
||||
|
||||
* Extended support for <<mapping-usage.linking, linking>> entities.
|
||||
|
||||
[[new-features.3.2]]
|
||||
== What's New in Spring Data MongoDB 3.2
|
||||
|
||||
|
||||
@@ -480,6 +480,7 @@ The MappingMongoConverter can use metadata to drive the mapping of objects to do
|
||||
* `@MongoId`: Applied at the field level to mark the field used for identity purpose. Accepts an optional `FieldType` to customize id conversion.
|
||||
* `@Document`: Applied at the class level to indicate this class is a candidate for mapping to the database. You can specify the name of the collection where the data will be stored.
|
||||
* `@DBRef`: Applied at the field to indicate it is to be stored using a com.mongodb.DBRef.
|
||||
* `@DocumentReference`: Applied at the field to indicate it is to be stored as a pointer to another document. This can be a single value (the _id_ by default), or a `Document` provided via a converter.
|
||||
* `@Indexed`: Applied at the field level to describe how to index the field.
|
||||
* `@CompoundIndex` (repeatable): Applied at the type level to declare Compound Indexes.
|
||||
* `@GeoSpatialIndexed`: Applied at the field level to describe how to geoindex the field.
|
||||
@@ -826,6 +827,370 @@ Required properties that are also defined as lazy loading ``DBRef`` and used as
|
||||
TIP: Lazily loaded ``DBRef``s can be hard to debug. Make sure tooling does not accidentally trigger proxy resolution by eg. calling `toString()` or some inline debug rendering invoking property getters.
|
||||
Please consider to enable _trace_ logging for `org.springframework.data.mongodb.core.convert.DefaultDbRefResolver` to gain insight on `DBRef` resolution.
|
||||
|
||||
[[mapping-usage.linking]]
|
||||
=== Using Document References
|
||||
|
||||
Using `@DocumentReference` offers an alternative way of linking entities in MongoDB.
|
||||
While the goal is the same as when using <<mapping-usage-references,DBRefs>>, the store representation is different.
|
||||
`DBRef` resolves to a document with a fixed structure as outlined in the https://docs.mongodb.com/manual/reference/database-references/[MongoDB Reference documentation]. +
|
||||
Document references, do not follow a specific format.
|
||||
They can be literally anything, a single value, an entire document, basically everything that can be stored in MongoDB.
|
||||
By default, the mapping layer will use the referenced entities _id_ value for storage and retrieval, like in the sample below.
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Document
|
||||
public class Account {
|
||||
|
||||
@Id
|
||||
private String id;
|
||||
private Float total;
|
||||
}
|
||||
|
||||
@Document
|
||||
public class Person {
|
||||
|
||||
@Id
|
||||
private String id;
|
||||
|
||||
@DocumentReference <1>
|
||||
private List<Account> accounts;
|
||||
}
|
||||
----
|
||||
[source,java]
|
||||
----
|
||||
Account account = ...
|
||||
|
||||
tempate.insert(account); <2>
|
||||
|
||||
template.update(Person.class)
|
||||
.matching(where("id").is(...))
|
||||
.apply(new Update().push("accounts").value(account)) <3>
|
||||
.first();
|
||||
----
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"_id" : ...,
|
||||
"accounts" : [ "6509b9e", ... ] <4>
|
||||
}
|
||||
----
|
||||
<1> Mark the collection of `Account` values to be linked.
|
||||
<2> The mapping framework does not handle cascading saves, so make sure to persist the referenced entity individually.
|
||||
<3> Add the reference to the existing entity.
|
||||
<4> Linked `Account` entities are represented as an array of their `_id` values.
|
||||
====
|
||||
|
||||
The sample above uses an `_id` based fetch query (`{ '_id' : ?#{#target} }`) for data retrieval and resolves linked entities eagerly.
|
||||
It is possible to alter resolution defaults (listed below) via the attributes of `@DocumentReference`
|
||||
|
||||
.@DocumentReference defaults
|
||||
[cols="2,3,5", options="header"]
|
||||
|===
|
||||
| Attribute | Description | Default
|
||||
|
||||
| `db`
|
||||
| The target database name for collection lookup.
|
||||
| The configured database provided by `MongoDatabaseFactory.getMongoDatabase()`.
|
||||
|
||||
| `collection`
|
||||
| The target collection name.
|
||||
| The annotated properties domain type, respectively the value type in case of `Collection` like or `Map` properties, collection name.
|
||||
|
||||
| `lookup`
|
||||
| The single document lookup query evaluating placeholders via SpEL expressions using `#target` as the marker for a given source value. `Collection` like or `Map` properties combine individual lookups via an `$or` operator.
|
||||
| An `_id` field based query (`{ '_id' : ?#{#target} }`) using the loaded source value.
|
||||
|
||||
| `lazy`
|
||||
| If set to `true` value resolution is delayed upon first access of the property.
|
||||
| Resolves properties eagerly by default.
|
||||
|===
|
||||
|
||||
`@DocumentReference(lookup=...)` allows to define custom queries that are independent from the `_id` field and therefore offer a flexible way of defining links between entities as demonstrated in the sample below, where the `Publisher` of a book is referenced by its acronym instead of the internal `id`.
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Document
|
||||
public class Book {
|
||||
|
||||
@Id
|
||||
private ObjectId id;
|
||||
private String title;
|
||||
private List<String> author;
|
||||
|
||||
@Field("publisher_ac")
|
||||
@DocumentReference(lookup = "{ 'acronym' : ?#{#target} }") <1>
|
||||
private Publisher publisher;
|
||||
}
|
||||
|
||||
@Document
|
||||
public class Publisher {
|
||||
|
||||
@Id
|
||||
private ObjectId id;
|
||||
private String acronym; <1>
|
||||
private String name;
|
||||
|
||||
@DocumentReference(lazy = true) <2>
|
||||
private List<Book> books;
|
||||
|
||||
}
|
||||
----
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"_id" : 9a48e32,
|
||||
"title" : "The Warded Man",
|
||||
"author" : ["Peter V. Brett"],
|
||||
"publisher_ac" : "DR"
|
||||
}
|
||||
----
|
||||
<1> Use the `acronym` field to query for entities in the `Publisher` collection.
|
||||
<2> Lazy load back references to the `Book` collection.
|
||||
====
|
||||
|
||||
The above snipped shows the reading side of things when working with custom linked objects.
|
||||
To make the writing part aware of the modified document pointer a custom converter, capable of the transformation into a `DocumentPointer`, like the one below, needs to be registered.
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@WritingConverter
|
||||
class PublisherReferenceConverter implements Converter<Publisher, DocumentPointer<String>> {
|
||||
|
||||
@Override
|
||||
public DocumentPointer<String> convert(Publisher source) {
|
||||
return () -> source.getAcronym();
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If no `DocumentPointer` converter is provided the target linkage document can be computed based on the given lookup query.
|
||||
In this case the association target properties are evaluated as shown in the following sample.
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Document
|
||||
public class Book {
|
||||
|
||||
@Id
|
||||
private ObjectId id;
|
||||
private String title;
|
||||
private List<String> author;
|
||||
|
||||
@DocumentReference(lookup = "{ 'acronym' : ?#{acc} }") <1> <2>
|
||||
private Publisher publisher;
|
||||
}
|
||||
|
||||
@Document
|
||||
public class Publisher {
|
||||
|
||||
@Id
|
||||
private ObjectId id;
|
||||
private String acronym; <1>
|
||||
private String name;
|
||||
|
||||
// ...
|
||||
}
|
||||
----
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"_id" : 9a48e32,
|
||||
"title" : "The Warded Man",
|
||||
"author" : ["Peter V. Brett"],
|
||||
"publisher" : {
|
||||
"acc" : "DOC"
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Use the `acronym` field to query for entities in the `Publisher` collection.
|
||||
<2> The field value placeholders of the lookup query (like `acc`) is used to form the linkage document.
|
||||
====
|
||||
|
||||
With all the above in place it is possible to model all kind of associations between entities.
|
||||
Have a look at the non exhaustive list of samples below to get feeling for what is possible.
|
||||
|
||||
.Simple Document Reference using _id_ field
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Entity {
|
||||
@DocumentReference
|
||||
private ReferencedObject ref;
|
||||
}
|
||||
----
|
||||
|
||||
[source,json]
|
||||
----
|
||||
// entity
|
||||
{
|
||||
"_id" : "8cfb002",
|
||||
"ref" : "9a48e32" <1>
|
||||
}
|
||||
|
||||
// referenced object
|
||||
{
|
||||
"_id" : "9a48e32" <1>
|
||||
}
|
||||
----
|
||||
<1> MongoDB simple type can be directly used without further configuration.
|
||||
====
|
||||
|
||||
.Simple Document Reference using _id_ field with explicit lookup query
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Entity {
|
||||
@DocumentReference(lookup = "{ '_id' : '?#{#target}' }") <1>
|
||||
private ReferencedObject ref;
|
||||
}
|
||||
----
|
||||
|
||||
[source,json]
|
||||
----
|
||||
// entity
|
||||
{
|
||||
"_id" : "8cfb002",
|
||||
"ref" : "9a48e32" <1>
|
||||
}
|
||||
|
||||
// referenced object
|
||||
{
|
||||
"_id" : "9a48e32"
|
||||
}
|
||||
----
|
||||
<1> _target_ defines the linkage value itself.
|
||||
====
|
||||
|
||||
.Document Reference extracting field of linkage document for lookup query
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Entity {
|
||||
@DocumentReference(lookup = "{ '_id' : '?#{refKey}' }") <1> <2>
|
||||
private ReferencedObject ref;
|
||||
}
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@WritingConverter
|
||||
class ToDocumentPointerConverter implements Converter<ReferencedObject, DocumentPointer<Document>> {
|
||||
public DocumentPointer<Document> convert(ReferencedObject source) {
|
||||
return () -> new Document("refKey", source.id); <1>
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
[source,json]
|
||||
----
|
||||
// entity
|
||||
{
|
||||
"_id" : "8cfb002",
|
||||
"ref" : {
|
||||
"refKey" : "9a48e32" <1>
|
||||
}
|
||||
}
|
||||
|
||||
// referenced object
|
||||
{
|
||||
"_id" : "9a48e32"
|
||||
}
|
||||
----
|
||||
<1> The key used for obtaining the linkage value must be the one used during write.
|
||||
<2> `refKey` is short for `target.refKey`.
|
||||
====
|
||||
|
||||
.Document Reference with multiple values forming the lookup query
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Entity {
|
||||
@DocumentReference(lookup = "{ 'firstname' : '?#{fn}', 'lastname' : '?#{ln}' }") <1> <2>
|
||||
private ReferencedObject ref;
|
||||
}
|
||||
----
|
||||
|
||||
[source,json]
|
||||
----
|
||||
// entity
|
||||
{
|
||||
"_id" : "8cfb002",
|
||||
"ref" : {
|
||||
"fn" : "Josh", <1>
|
||||
"ln" : "Long" <1>
|
||||
}
|
||||
}
|
||||
|
||||
// referenced object
|
||||
{
|
||||
"_id" : "9a48e32",
|
||||
"firsntame" : "Josh", <2>
|
||||
"lastname" : "Long", <2>
|
||||
}
|
||||
----
|
||||
<1> Read/wirte the keys `fn` & `ln` from/to the linkage document based on the lookup query.
|
||||
<2> Use non _id_ fields for the lookup of the target documents.
|
||||
====
|
||||
|
||||
.Document Reference reading target collection from linkage document
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Entity {
|
||||
@DocumentReference(lookup = "{ '_id' : '?#{id}' }", collection = "?#{collection}") <2>
|
||||
private ReferencedObject ref;
|
||||
}
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@WritingConverter
|
||||
class ToDocumentPointerConverter implements Converter<ReferencedObject, DocumentPointer<Document>> {
|
||||
public DocumentPointer<Document> convert(ReferencedObject source) {
|
||||
return () -> new Document("id", source.id) <1>
|
||||
.append("collection", ... ); <2>
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
[source,json]
|
||||
----
|
||||
// entity
|
||||
{
|
||||
"_id" : "8cfb002",
|
||||
"ref" : {
|
||||
"id" : "9a48e32", <1>
|
||||
"collection" : "..." <2>
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Read/wirte the keys `_id` from/to the linkage document to use them in the lookup query.
|
||||
<2> The collection name can be read from the linkage document via its key.
|
||||
====
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
We know it is tempting to use all kinds of MongoDB query operators in the lookup query and this is fine. But:
|
||||
|
||||
* Make sure to have indexes in place that support your lookup.
|
||||
* Mind that resolution takes time and consider a lazy strategy.
|
||||
* A collection of document references is bulk loaded using an `$or` operator. +
|
||||
The original element order is restored in memory which cannot be done when using MongoDB query operators.
|
||||
In this case Results will be ordered as they are received from the store.
|
||||
|
||||
And a few more general remarks:
|
||||
|
||||
* Cyclic references? Ask your self if you need them.
|
||||
* Lazy document references are hard to debug. Make sure tooling does not accidentally trigger proxy resolution by eg. calling `toString()`.
|
||||
* There is no support for reading document references via the reactive bits Spring Data MongoDB offers.
|
||||
====
|
||||
|
||||
[[mapping-usage-events]]
|
||||
=== Mapping Framework Events
|
||||
|
||||
|
||||
Reference in New Issue
Block a user