Skip to content

HSEARCH-4508 + HSEARCH-4510 Migration guide improvements #2945

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 15, 2022
Merged

HSEARCH-4508 + HSEARCH-4510 Migration guide improvements #2945

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a57313
HSEARCH-4508 Document the equivalent of aws.* properties in the migra…
yrodiere Mar 15, 2022
bc4b31a
HSEARCH-4510 Fix copy/paste errors in Search DSL examples in the migr…
yrodiere Mar 15, 2022
1c7e7db
HSEARCH-4510 Add recommended approach for boolean predicate nesting i…
yrodiere Mar 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 65 additions & 24 deletions documentation/src/main/asciidoc/migration/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,7 @@ In Hibernate Search 6, constants are provided through classes whose name ends wi
* `org.hibernate.search.backend.lucene.cfg.LuceneIndexSettings`
* `org.hibernate.search.backend.elasticsearch.cfg.ElasticsearchBackendSettings`
* `org.hibernate.search.backend.elasticsearch.cfg.ElasticsearchIndexSettings`
* `org.hibernate.search.backend.elasticsearch.aws.cfg.ElasticsearchAwsBackendSettings`

[[configuration-property-reference]]
=== [[_configuration_property_reference]] Configuration property reference
Expand Down Expand Up @@ -240,6 +241,30 @@ Hibernate Search 6 will automatically turn entities to documents
and hold documents in memory until the transaction commit.
+
See also link:{hibernateSearchDocUrl}#mapper-orm-indexing-manual[this section of the documentation].
`hibernate.search.default.elasticsearch.aws.*`::
The syntax for configuring AWS authentication changed slightly in Hibernate Search 6.
+
In short, the following configuration in Hibernate Search 5:
[source]
----
hibernate.search.default.elasticsearch.aws.signing.enabled = true
hibernate.search.default.elasticsearch.aws.region = us-east-1
hibernate.search.default.elasticsearch.aws.access_key = AKIDEXAMPLE
hibernate.search.default.elasticsearch.aws.secret_key = wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY
----
+
Will look like this in Hibernate Search 6:
[source]
----
hibernate.search.backend.aws.signing.enabled = true
hibernate.search.backend.aws.region = us-east-1
hibernate.search.backend.aws.credentials.type = static
hibernate.search.backend.aws.credentials.access_key_id = AKIDEXAMPLE
hibernate.search.backend.aws.credentials.secret_access_key = wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY
----
+
Other types of credentials are available in Hibernate Search 6,
see link:{hibernateSearchDocUrl}#backend-elasticsearch-configuration-aws[this section of the documentation]
`hibernate.search.default.elasticsearch.connection_timeout`::
Hibernate Search 6 equivalent: `hibernate.search.backend.connection_timeout`.
+
Expand Down Expand Up @@ -1964,7 +1989,7 @@ As to migrating existing complex queries, let's consider the query below:

[source, JAVA]
----
MySearchParameters params = ...;
MySearchParameters searchParameters = ...;
FullTextEntityManager fullTextEntityManager = Search.getFullTextEntityManager( em );
QueryBuilder qb = fullTextEntityManager.getSearchFactory()
.buildQueryBuilder().forEntity( Book.class ).get();
Expand All @@ -1978,14 +2003,18 @@ if ( searchParameters.getSearchTerms() != null ) {
.matching( searchParameters.getSearchTerms() )
.createQuery() );
}
if ( searchParameters.getGenre() != null ) {
junction.must( qb.keyword().onField( "genre" )
.matching( searchParameters.getGenre() ) );
}
if ( searchParameters.getMaxBookLength() != null ) {
junction.must( qb.range().onField( "pageCount" )
.below( searchParameters.getMaxBookLength() ) );
}
if ( !searchParameters.getGenres().isEmpty() ) {
BooleanJunction junction2 = qb.bool();
for ( Genre genre : searchParameters.getGenres() ) {
junction2.should( qb.keyword().onField( "genre" )
.matching( genre ) );
}
junction.must( junction2.createQuery() );
}

org.apache.lucene.search.Query luceneQuery = junction.createQuery();

Expand All @@ -2000,7 +2029,7 @@ It would look like this in Hibernate Search 6:

[source, JAVA]
----
MySearchParameters params = ...;
MySearchParameters searchParameters = ...;
SearchSession session = Search.session( entityManager );
List<Book> hits = searchSession.search( Book.class )
.where( f -> f.bool( b -> {
Expand All @@ -2010,23 +2039,28 @@ List<Book> hits = searchSession.search( Book.class )
.matching( searchParameters.getSearchTerms() )
.defaultOperator( BooleanOperator.AND ) );
}
if ( searchParameters.getGenre() != null ) {
b.must( f.match().field( "genre" )
.matching( searchParameters.getGenre() ) );
}
if ( searchParameters.getMaxBookLength() != null ) {
b.must( f.range().field( "pageCount" )
.atMost( searchParameters.getMaxBookLength() ) );
}
if ( !searchParameters.getGenres().isEmpty() ) {
b.must( f.bool( b2 -> {
for ( Genre genre : searchParameters.getGenres() ) {
b2.should( f.match().field( "genre" )
.matching( genre ) );
}
} ) );
}
} ) )
.fetchHits( params.getPageIndex() * params.getPageSize(), params.getPageSize() );
.fetchHits( searchParameters.getPageIndex() * searchParameters.getPageSize(),
searchParameters.getPageSize() );
----

Alternatively, if for some reasons predicate objects are necessary:

[source, JAVA]
----
MySearchParameters params = ...;
MySearchParameters searchParameters = ...;
SearchSession session = Search.session( entityManager );
SearchPredicateFactory pf = session.scope( Book.class ).predicate();
List<SearchPredicate> predicates = new ArrayList<>();
Expand All @@ -2037,25 +2071,32 @@ if ( searchParameters.getSearchTerms() != null ) {
.defaultOperator( BooleanOperator.AND )
.toPredicate() );
}
if ( searchParameters.getGenre() != null ) {
predicates.add( pf.match().field( "genre" )
.matching( searchParameters.getGenre() )
.toPredicate() );
}
if ( searchParameters.getMaxBookLength() != null ) {
predicates.add( pf.range().field( "pageCount" )
.atMost( searchParameters.getMaxBookLength() )
.toPredicate() );
}
if ( !searchParameters.getGenres().isEmpty() ) {
predicates.add( f.bool( b -> {
for ( Genre genre : searchParameters.getGenres() ) {
b.should( f.match().field( "genre" )
.matching( genre ) );
}
} )
.toPredicate() );
}

SearchPredicate topLevelPredicate = pf.bool( b -> {
b.must( f.matchAll() );
for ( SearchPredicate predicate : predicates ) {
b.must( predicate );
}
} );

List<Book> hits = searchSession.search( Book.class )
.where( f -> f.bool( b -> {
b.must( f.matchAll() );
for ( SearchPredicate predicate : predicates ) {
b.must( predicate );
}
} )
.fetchHits( params.getPageIndex() * params.getPageSize(), params.getPageSize() );
.where( topLevelPredicate )
.fetchHits( searchParameters.getPageIndex() * searchParameters.getPageSize(),
searchParameters.getPageSize() );
----

[[queries-reference]]
Expand Down