HSEARCH-3615 Document the query DSL in details

documentation/src/main/asciidoc/getting-started.asciidoc

@@ -290,7 +290,7 @@ include::{sourcedir}/org/hibernate/search/documentation/gettingstarted/withhsear
 <2> Initiate a search query on the index mapped to the `Book` entity.
 <3> Define that only documents matching the given predicate should be returned.
 The predicate is created using a factory `f` passed as an argument to the lambda expression.
-<4> Build the query and fetch the results.
+<4> Build the query and fetch the results, limiting to the top 20 hits.
 <5> Retrieve the total number of matching entities.
 <6> Retrieve matching entities.
 <7> In case you're not interested in the whole result, but only in the hits,
@@ -311,7 +311,7 @@ include::{sourcedir}/org/hibernate/search/documentation/gettingstarted/withhsear
 <3> Initiate a search query targeting the search scope.
 <4> Define that only documents matching the given predicate should be returned.
 The predicate is created using the same search scope as the query.
-<5> Build the query and fetch the results.
+<5> Build the query and fetch the results, limiting to the top 20 hits.
 <6> Retrieve the total number of matching entities.
 <7> Retrieve matching entities.
 <8> In case you're not interested in the whole result, but only in the hits,

documentation/src/test/java/org/hibernate/search/documentation/gettingstarted/withhsearch/withanalysis/GettingStartedWithAnalysisIT.java

@@ -83,7 +83,7 @@ public void test() {
 							.fields( "title", "authors.name" )
 							.matching( "refactor" )
 					)
-					.fetch();
+					.fetch( 20 );
 			// Not shown: commit the transaction and close the entity manager
 			// end::searching[]
 
@@ -101,7 +101,7 @@ public void test() {
 								.fields( "title", "authors.name" )
 								.matching( term )
 						)
-						.fetch();
+						.fetch( 20 );
 				assertThat( result.getHits() ).as( "Result of searching for '" + term + "'" )
 						.extracting( "id" )
 						.containsExactlyInAnyOrder( bookIdHolder.get() );

documentation/src/test/java/org/hibernate/search/documentation/gettingstarted/withhsearch/withoutanalysis/GettingStartedWithoutAnalysisIT.java

@@ -110,7 +110,7 @@ public void test() {
 							.matching( "Refactoring: Improving the Design of Existing Code" )
 							.toPredicate()
 					)
-					.fetch(); // <5>
+					.fetch( 20 ); // <5>
 
 			long totalHitCount = result.getTotalHitCount(); // <6>
 			List<Book> hits = result.getHits(); // <7>
@@ -125,7 +125,7 @@ public void test() {
 							.toPredicate()
 					)
 			// tag::searching-objects[]
-					.fetchHits(); // <8>
+					.fetchHits( 20 ); // <8>
 			// Not shown: commit the transaction and close the entity manager
 			// end::searching-objects[]
 
@@ -146,7 +146,7 @@ public void test() {
 							.fields( "title", "authors.name" )
 							.matching( "Refactoring: Improving the Design of Existing Code" )
 					)
-					.fetch(); // <4>
+					.fetch( 20 ); // <4>
 
 			long totalHitCount = result.getTotalHitCount(); // <5>
 			List<Book> hits = result.getHits(); // <6>
@@ -160,7 +160,7 @@ public void test() {
 									.matching( "Refactoring: Improving the Design of Existing Code" )
 							)
 			// tag::searching-lambdas[]
-					.fetchHits(); // <7>
+					.fetchHits( 20 ); // <7>
 			// Not shown: commit the transaction and close the entity manager
 			// end::searching-lambdas[]
 

documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/directfieldmapping/HibernateOrmSimpleMappingIT.java

@@ -76,7 +76,7 @@ public void sort() {
 					.sort( f -> f.field( "pageCount" ).desc() // <2>
 							.then().field( "title_sort" )
 					)
-					.fetchHits(); // <3>
+					.fetchHits( 20 ); // <3>
 
 			assertThat( result )
 					.extracting( "title" )
@@ -92,7 +92,7 @@ public void projection_simple() {
 			List<String> result = searchSession.search( Book.class ) // <1>
 					.asProjection( f -> f.field( "title", String.class ) ) // <2>
 					.predicate( f -> f.matchAll() )
-					.fetchHits(); // <3>
+					.fetchHits( 20 ); // <3>
 
 			assertThat( result )
 					.containsExactlyInAnyOrder( BOOK1_TITLE, BOOK2_TITLE, BOOK3_TITLE );

documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/entityindexmapping/HibernateOrmIndexedIT.java

@@ -74,12 +74,12 @@ public void search_separateQueries() {
 
 			List<Author> authorResult = searchSession.search( Author.class )
 					.predicate( f -> f.matchAll() )
-					.fetchHits();
+					.fetchHits( 20 );
 			assertThat( authorResult ).hasSize( 1 );
 
 			List<User> userResult = searchSession.search( User.class )
 					.predicate( f -> f.matchAll() )
-					.fetchHits();
+					.fetchHits( 20 );
 			assertThat( userResult ).hasSize( 1 );
 		} );
 	}
@@ -96,7 +96,7 @@ public void search_singleQuery() {
 									Arrays.asList( Author.class, User.class )
 							)
 							.predicate( f -> f.matchAll() )
-							.fetchHits();
+							.fetchHits( 20 );
 					// end::cross-backend-search[]
 				} )
 		)

documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/indexing/HibernateOrmAutomaticIndexingIT.java

@@ -77,7 +77,7 @@ public void synchronizationStrategyOverride() {
 
 			List<Book> result = searchSession.search( Book.class )
 					.predicate( f -> f.match().field( "title" ).matching( "2nd edition" ) )
-					.fetchHits(); // <5>
+					.fetchHits( 20 ); // <5>
 			// end::automatic-indexing-synchronization-strategy-override[]
 
 			assertThat( result ).extracting( Book::getId )

documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/routing/HibernateOrmRoutingIT.java

@@ -71,7 +71,7 @@ public void routing_single() {
 							.field( "genre" )
 							.matching( Genre.SCIENCE_FICTION ) ) // <2>
 					.routing( Genre.SCIENCE_FICTION.name() ) // <3>
-					.fetch(); // <4>
+					.fetch( 20 ); // <4>
 			// end::routing-single[]
 
 			// We can't really test whether sharding worked here; see the backend TCK for such test.

documentation/src/test/java/org/hibernate/search/documentation/searchdsl/aggregation/AggregationDslIT.java

@@ -84,7 +84,7 @@ public void entryPoint() {
 							.matching( "robot" ) )
 					.aggregation( countsByGenreKey, f -> f.terms() // <4>
 							.field( "genre", Genre.class ) )
-					.fetch(); // <5>
+					.fetch( 20 ); // <5>
 
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey ); // <6>
 			// end::entryPoint-lambdas[]
@@ -109,7 +109,7 @@ public void entryPoint() {
 					.aggregation( countsByGenreKey, scope.aggregation().terms()
 							.field( "genre", Genre.class )
 							.toAggregation() )
-					.fetch();
+					.fetch( 20 );
 
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::entryPoint-objects[]
@@ -129,7 +129,7 @@ public void terms() {
 					.predicate( f -> f.matchAll() )
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class ) ) // <1>
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms[]
 			assertThat( countsByGenre )
@@ -146,7 +146,7 @@ public void terms() {
 					.predicate( f -> f.matchAll() )
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", String.class, ValueConvert.NO ) )
-					.fetch();
+					.fetch( 20 );
 			Map<String, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-noConverter[]
 			assertThat( countsByGenre )
@@ -164,7 +164,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.maxTermCount( 1 ) )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-max-term-count[]
 			assertThat( countsByGenre )
@@ -181,7 +181,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.minDocumentCount( 0 ) )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-min-doc-count-zero[]
 			assertThat( countsByGenre )
@@ -199,7 +199,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.minDocumentCount( 2 ) )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-min-doc-count-high[]
 			assertThat( countsByGenre )
@@ -216,7 +216,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.orderByTermAscending() )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-order-term-ascending[]
 			assertThat( countsByGenre )
@@ -234,7 +234,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.orderByTermDescending() )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-order-term-descending[]
 			assertThat( countsByGenre )
@@ -252,7 +252,7 @@ public void terms() {
 					.aggregation( countsByGenreKey, f -> f.terms()
 							.field( "genre", Genre.class )
 							.orderByCountAscending() )
-					.fetch();
+					.fetch( 20 );
 			Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );
 			// end::terms-order-count-ascending[]
 			assertThat( countsByGenre )
@@ -276,7 +276,7 @@ public void range() {
 							.range( 10.0, 20.0 )
 							.range( 20.0, null ) // <3>
 					)
-					.fetch();
+					.fetch( 20 );
 			Map<Range<Double>, Long> countsByPrice = result.getAggregation( countsByPriceKey );
 			// end::range[]
 			assertThat( countsByPrice )
@@ -299,7 +299,7 @@ public void range() {
 									20.0, RangeBoundInclusion.EXCLUDED ) ) // <2>
 							.range( Range.atLeast( 20.0 ) ) // <3>
 					)
-					.fetch();
+					.fetch( 20 );
 			Map<Range<Double>, Long> countsByPrice = result.getAggregation( countsByPriceKey );
 			// end::range-objects[]
 			assertThat( countsByPrice )
@@ -329,7 +329,7 @@ public void range() {
 											.atStartOfDay().toInstant( ZoneOffset.UTC ),
 									null )
 					)
-					.fetch();
+					.fetch( 20 );
 			Map<Range<Instant>, Long> countsByPrice = result.getAggregation( countsByPriceKey );
 			// end::range-noConverter[]
 			assertThat( countsByPrice )

documentation/src/test/java/org/hibernate/search/documentation/searchdsl/converter/DslConverterIT.java

@@ -73,7 +73,7 @@ public void dslConverterEnabled() {
 			List<AuthenticationEvent> result = searchSession.search( AuthenticationEvent.class )
 					.predicate( f -> f.match().field( "outcome" )
 							.matching( AuthenticationOutcome.INVALID_PASSWORD ) )
-					.fetchHits();
+					.fetchHits( 20 );
 			// end::dsl-converter-enabled[]
 
 			assertThat( result )
@@ -91,7 +91,7 @@ public void dslConverterDisabled() {
 			List<AuthenticationEvent> result = searchSession.search( AuthenticationEvent.class )
 					.predicate( f -> f.match().field( "outcome" )
 							.matching( "Invalid password", ValueConvert.NO ) )
-					.fetchHits();
+					.fetchHits( 20 );
 			// end::dsl-converter-disabled[]
 
 			assertThat( result )

documentation/src/test/java/org/hibernate/search/documentation/searchdsl/converter/ProjectionConverterIT.java

@@ -73,7 +73,7 @@ public void projectionConverterEnabled() {
 			List<OrderStatus> result = searchSession.search( Order.class )
 					.asProjection( f -> f.field( "status", OrderStatus.class ) )
 					.predicate( f -> f.matchAll() )
-					.fetchHits();
+					.fetchHits( 20 );
 			// end::projection-converter-enabled[]
 
 			assertThat( result )
@@ -90,7 +90,7 @@ public void projectionConverterDisabled() {
 			List<String> result = searchSession.search( Order.class )
 					.asProjection( f -> f.field( "status", String.class, ValueConvert.NO ) )
 					.predicate( f -> f.matchAll() )
-					.fetchHits();
+					.fetchHits( 20 );
 			// end::projection-converter-disabled[]
 
 			assertThat( result )