From 921d035f8d77136103b9218f0d03ce57e7f5b4a2 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 19 Mar 2025 09:42:24 +0100 Subject: [PATCH] Refine `@DocumentReference` documentation about `self._id` references. Closes #4925 --- .../ROOT/pages/mongodb/mapping/document-references.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/main/antora/modules/ROOT/pages/mongodb/mapping/document-references.adoc b/src/main/antora/modules/ROOT/pages/mongodb/mapping/document-references.adoc index d1ef6b806..1dec452dc 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/mapping/document-references.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/mapping/document-references.adoc @@ -487,7 +487,9 @@ We know it is tempting to use all kinds of MongoDB query operators in the lookup But there a few aspects to consider: * Make sure to have indexes in place that support your lookup. -* Mind that resolution requires a server rountrip inducing latency, consider a lazy strategy. +* Make sure to use the same data types: `@DocumentReference(lookup="{'someRef':?#{#self._id} }")` can easily fail when using `@Id String id` and `String someRef` as ``String @Id``'s are subject to automatic ObjectId conversion (but not other `String` properties containing `ObjectId.toString()`). +Reference lookup uses values from the resulting `Document` and in that case, it would query a String field using an `ObjectId` yielding no results. +* Mind that resolution requires a server roundtrip inducing latency, consider a lazy strategy. * A collection of document references is bulk loaded using the `$or` operator. + The original element order is restored in memory on a best-effort basis. Restoring the order is only possible when using equality expressions and cannot be done when using MongoDB query operators.