Update QBE Documentation section.

This commit adds a note explaining scenarios suitable for an UntypedExampleMatcher.

Closes: #3474
Original pull request: #3538.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Criteria.java

@@ -124,7 +124,12 @@ public static Criteria byExample(Object example) {
 	}
 
 	/**
-	 * Static factory method to create a {@link Criteria} matching an example object.
+	 * Static factory method to create a {@link Criteria} matching an example object. <br />
+	 * By default the {@link Example} uses typed matching restricting it to probe assignable types. For example, when
+	 * sticking with the default type key ({@code _class}), the query has restrictions such as
+	 * <code>_class : &#123; $in : [com.acme.Person] &#125; </code>. <br />
+	 * To avoid the above mentioned type restriction use an {@link UntypedExampleMatcher} with
+	 * {@link Example#of(Object, org.springframework.data.domain.ExampleMatcher)}.
 	 *
 	 * @param example must not be {@literal null}.
 	 * @return new instance of {@link Criteria}.

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/MongoRepository.java

@@ -78,16 +78,31 @@ public interface MongoRepository<T, ID> extends PagingAndSortingRepository<T, ID
 	 */
 	<S extends T> List<S> insert(Iterable<S> entities);
 
-	/*
-	 * (non-Javadoc)
+	/**
+	 * Returns all entities matching the given {@link Example}. In case no match could be found an empty {@link List} is
+	 * returned. <br />
+	 * By default the {@link Example} uses typed matching restricting it to probe assignable types. For example, when
+	 * sticking with the default type key ({@code _class}), the query has restrictions such as
+	 * <code>_class : &#123; $in : [com.acme.Person] &#125;</code>. <br />
+	 * To avoid the above mentioned type restriction use an {@link org.springframework.data.mongodb.core.query.UntypedExampleMatcher} with
+	 * {@link Example#of(Object, org.springframework.data.domain.ExampleMatcher)}.
+	 *
 	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example)
 	 */
 	@Override
 	<S extends T> List<S> findAll(Example<S> example);
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example, org.springframework.data.domain.Sort)
+	/**
+	 * Returns all entities matching the given {@link Example} applying the given {@link Sort}. In case no match could be
+	 * found an empty {@link List} is returned. <br />
+	 * By default the {@link Example} uses typed matching restricting it to probe assignable types. For example, when
+	 * sticking with the default type key ({@code _class}), the query has restrictions such as
+	 * <code>_class : &#123; $in : [com.acme.Person] &#125;</code>. <br />
+	 * To avoid the above mentioned type restriction use an {@link org.springframework.data.mongodb.core.query.UntypedExampleMatcher} with
+	 * {@link Example#of(Object, org.springframework.data.domain.ExampleMatcher)}.
+	 *
+	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example,
+	 *      org.springframework.data.domain.Sort)
 	 */
 	@Override
 	<S extends T> List<S> findAll(Example<S> example, Sort sort);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/ReactiveMongoRepository.java

@@ -64,16 +64,33 @@ public interface ReactiveMongoRepository<T, ID> extends ReactiveSortingRepositor
 	 */
 	<S extends T> Flux<S> insert(Publisher<S> entities);
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example)
+	/**
+	 * Returns all entities matching the given {@link Example}. In case no match could be found an empty {@link Flux} is
+	 * returned. <br />
+	 * By default the {@link Example} uses typed matching restricting it to probe assignable types. For example, when
+	 * sticking with the default type key ({@code _class}), the query has restrictions such as
+	 * <code>_class : &#123; $in : [com.acme.Person] &#125;</code>. <br />
+	 * To avoid the above mentioned type restriction use an {@link org.springframework.data.mongodb.core.query.UntypedExampleMatcher} with
+	 * {@link Example#of(Object, org.springframework.data.domain.ExampleMatcher)}.
+	 *
+	 * @see org.springframework.data.repository.query.ReactiveQueryByExampleExecutor#findAll(org.springframework.data.domain.Example)
 	 */
+	@Override
 	<S extends T> Flux<S> findAll(Example<S> example);
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example, org.springframework.data.domain.Sort)
+	/**
+	 * Returns all entities matching the given {@link Example} applying the given {@link Sort}. In case no match could be
+	 * found an empty {@link Flux} is returned. <br />
+	 * By default the {@link Example} uses typed matching restricting it to probe assignable types. For example, when
+	 * sticking with the default type key ({@code _class}), the query has restrictions such as
+	 * <code>_class : &#123; $in : [com.acme.Person] &#125;</code>. <br />
+	 * To avoid the above mentioned type restriction use an {@link org.springframework.data.mongodb.core.query.UntypedExampleMatcher} with
+	 * {@link Example#of(Object, org.springframework.data.domain.ExampleMatcher)}.
+	 *
+	 * @see org.springframework.data.repository.query.ReactiveQueryByExampleExecutor#findAll(org.springframework.data.domain.Example,
+	 *      org.springframework.data.domain.Sort)
 	 */
+	@Override
 	<S extends T> Flux<S> findAll(Example<S> example, Sort sort);
 
 }

src/main/asciidoc/reference/query-by-example.adoc

@@ -97,3 +97,10 @@ Query query = new Query(new Criteria().alike(example));
 List<Person> result = template.find(query, Person.class);
 ----
 ====
+
+[NOTE]
+====
+`UntypedExampleMatcher` is likely the right choice for you if you are storing different entities within a single collection or opted out of writing <<mongo-template.type-mapping,type hints>>.
+
+Also, keep in mind that using `@TypeAlias` requires eager initialization of the `MappingContext`. To do so, configure `initialEntitySet` to to ensure proper alias resolution for read operations.
+====