Hibernate Search

5.8 series end-of-life

Experimental integration with Elasticsearch 5.x, AWS integration, improvements and deprecations paving the road to Search 6

Compatibility

Java 8
Hibernate ORM 5.2 (>= 5.2.3.Final)
Elasticsearch server 2.0 - 5.6
Apache Lucene 5.5

Not compatible with your requirements? Have a look at the other series.

See also the Compatibility policy and Maintenance policy.

Documentation

Documentation for Hibernate Search 5.8 can be accessed through the links below:

HTML PDF API (JavaDoc)

You can find more documentation for all series on the documentation page.

How to get it

Hibernate Search 5.8 has reached its end-of-life: we recommend that you upgrade to a newer series if possible.

See also the Maintenance policy.

Maven, Gradle...

Maven artifacts of Hibernate Search are published to Maven Central. Most build tools fetch artifacts from Maven Central by default, but if that's not the case for you, see this page to configure your build tool.

You can find the Maven coordinates of all artifacts through the link below:

Maven artifacts

Below are the Maven coordinates of the main artifacts.

org.hibernate:hibernate-search-orm:5.8.2.Final
Hibernate ORM integration
org.hibernate:hibernate-search-elasticsearch:5.8.2.Final
Elasticsearch integration
org.hibernate:hibernate-search-elasticsearch-aws:5.8.2.Final
Amazon IAM authentication for Elasticsearch
org.hibernate:hibernate-search-backend-jgroups:5.8.2.Final
JGroups backend
org.hibernate:hibernate-search-backend-jms:5.8.2.Final
JMS backend

All Maven artifacts of this project released after 2022-01-26 are signed.

To verify signed Maven artifacts, head to this page.

Direct download

A ZIP archive containing all JAR files, documentation and source is available from SourceForge:

Download ZIP archive

Individual Maven artifacts may be downloaded directly from the Maven repository:

Maven Central subdirectory

See here for how to download all dependencies of your Maven project to a local directory on your filesystem.

See here for how to download an explicitly listed set of artifacts to a local directory on your filesystem.

More information about specific releases (announcements, download links) can be found here.

Migrating

If you need to upgrade from a previous series, please refer to the migration guide:

HTML

What's new

Latest release announcement (2017-10-26): 5.8.2.Final.

A detailed list of new features, improvements and fixes in this series can be found on our issue tracker.

Elasticsearch 5.x support

Hibernate Search now integrates with Elasticsearch 5.x.

The new driver is backwards compatible, so we’ll still be able to connect to clusters running Elasticsearch 2.x.

This doesn’t need any configuration flag as Hibernate Search can automatically detect the version of Elasticsearch it’s being pointed to.

The features supported by Elasticsearch 5.x and 2.x are however slightly different and you’ll find that some low level mapping features are documented as compatible with only one specific version.

Also, due to major changes in Elasticsearch 5, migration from 2 to 5 (as well as from 5.0/5.1 to 5.2 in certain conditions) will require full reindexing. The migration guide will be updated when this minor release will be feature complete.

New improved Elasticsearch client

This release now uses the new Elasticsearch REST client, which is expected to be a safe choice in terms of long term maintenance as it’s sponsored and recommended by the Elasticsearch team.

Compared to the driver we used previously, this one uses a state of the art reactive architecture, so we can take advantage of more efficient resource utilization.

New Simple Query String supported by the Query builder DSL

The useful capabilities from Lucene’s SimpleQueryParser are now conveniently exposed by our higher level DSL.

Details about this feature are available in the documentation, and also in this blog post.

Simplified JNDI configuration

If you integrated any external component into Hibernate Search using JNDI, for example a JMS queue or an Infinispan cache, this configuration was simplified.

You will no longer need to set Hibernate Search specific configuration properties such as how to set the InitialContext for JNDI lookups: only configure Hibernate ORM, and Hibernate Search will inherit the same settings.

Programmatic analyzer definitions

You can now define your analyzers programmatically (without annotations), globally (without putting the definition on a particular entity), and in a native way (without using Lucene classes to configure an Elasticsearch analyzer) using analyzer definition providers.

For example, for Lucene your LuceneAnalysisDefinitionProvider might look like this:

public static class CustomAnalyzerProvider implements LuceneAnalysisDefinitionProvider {
    @Override
    public void register(LuceneAnalyzerDefinitionRegistryBuilder builder) {
        builder
                .analyzer( "myAnalyzer" )
                        .tokenizer( StandardTokenizerFactory.class )
                        .charFilter( MappingCharFilterFactory.class )
                                .param( "mapping", "org/hibernate/search/test/analyzer/mapping-chars.properties" )
                        .tokenFilter( ASCIIFoldingFilterFactory.class )
                        .tokenFilter( LowerCaseFilterFactory.class )
                        .tokenFilter( StopFilterFactory.class )
                                .param( "mapping", "org/hibernate/search/test/analyzer/stoplist.properties" )
                                .param( "ignoreCase", "true" );
    }
}

While for Elasticsearch you would have:

public static class CustomAnalyzerProvider implements ElasticsearchAnalysisDefinitionProvider {
    @Override
    public void register(ElasticsearchAnalysisDefinitionRegistryBuilder builder) {
        builder.analyzer( "tweet_analyzer" )
                .withTokenizer( "whitespace" )
                .withCharFilters( "custom_html_strip" )
                .withCharFilters( "p_br_as_space" );

        builder.charFilter( "custom_html_strip" )
                .type( "html_strip" )
                .param( "escaped_tags", "br", "p" );

        builder.charFilter( "p_br_as_space" )
                .type( "pattern_replace" )
                .param( "pattern", "<p/?>|<br/?>" )
                .param( "replacement", " " )
                .param( "tags", "CASE_INSENSITIVE" );
    }
}

As you can see, this allows you to avoid needing to refer to Lucene classes to configure Elasticsearch analyzers.

More details can be found here for Lucene and here for Elasticsearch.

Normalizers for safer sorts

In HSEARCH-2726 and HSEARCH-2659 we introduced normalizers: analyzers that do not perform any kind of tokenization.

We shamelessly borrowed this concept from Elasticsearch, but implemented it in both embedded Lucene mode and Elasticsearch mode. Normalizers are useful for sortable fields: when a field is sortable it should never be tokenized, as this would make the sort order unpredictable; the sort could apply to the first token if you’re lucky, but it could be applied on any other token.

From version 5.8.0.Beta3 onwards, Hibernate Search will log warnings whenever you’re using an analyzer on a sortable field. To resolve this warning change your Analyzer definition to be a Normalizer.

In Lucene, normalizers are just here to help, they work exactly as analyzers. The two differences are that you can’t affect a tokenizer to a normalizer when defining it, and that normalizers have a runtime safety net: should you manage to create multiple tokens, Hibernate Search will concatenate them back to a single token and log a warning.

In Elasticsearch version 5.2 and above, a normalizer will be translated to a native Elasticsearch normalizer, and a text field with a normalizer will take the keyword datatype.

In Elasticsearch version 5.1 and below, native normalizers are not available, thus normalizers are simply translated to analyzers and a text field with a normalizer will take the text (5.x) or string (2.x) datatype.

You can find out more about normalizers in the reference documentation:

AWS integration

We added a new module allowing you to very simply wire your Hibernate Search instance to an AWS-hosted Elasticsearch cluster using Amazon’s proprietary IAM authentication mechanism.

You can find more information about how to use this integration in the reference documentation.

Dependency injection in FieldBridges

As part of HSEARCH-1316, we’re experimenting with integration with various dependency injection frameworks.

The integration is about allowing you to use annotations such as @Inject, @PostConstruct and so on in your FieldBridges, which may for example allow you to fetch additional data from your application when indexing a given bean.

Integration is currently known to work with Spring DI and CDI. We don’t provide packages for user consumption, but if you are an integrator, or simply if you feel like it, you can have a look at our integration tests:

Releases in this series

Hibernate Search 5.8 has reached its end-of-life: we recommend that you upgrade to a newer series if possible.

See also the Maintenance policy.

5.8.2.Final

2017-10-26

5.8.0.Beta4

2017-07-18

New hibernate-search-elasticsearch-aws module for Amazon’s IAM authentication

Maven artifacts Download Resolved issues Release announcement

5.8.0.Beta3

2017-06-13

Analyzer providers, normalizers, new SPIs for integration with dependency injection frameworks

Maven artifacts Download Resolved issues Release announcement

5.8.0.Beta1

2017-04-15

Experimental integration with Elasticsearch 5.x, Simple Query String

Maven artifacts Download Resolved issues Release announcement

Back to top