This page is out of date: only versions of Hibernate Search prior to 5.5 are covered. For more recent versions see there.
Hibernate Search 5.4
This now requires using at least Hibernate ORM version 5.0.0.CR1 !
(No other notable API changes)
Hibernate Search 5.3
New Faceting engine: using faceting on a field now required to add the @Facet or @Facets annotations to mark which fields should support faceting. See also In Relation To... Hibernate Search 5.3.0.Beta1 with native Lucene faceting
(No other notable API changes)
Hibernate Search 5.2
Upgraded to Infinispan 7.2
(No other notable API changes)
Hibernate Search 5.1
Annotation org.hibernate.search.annotations.Key is deprecated. There is no replacement, it's simply no longer required for users to provide a key object.
Hibernate Search 5
For users upgrading from Hibernate Search 4 to 5 directly (skipping the development builds) it might be simpler to read the dedicated migration page on the website.
The following paragraphs detail the changes between each released tag.
Hibernate Search 5.0.0.Final
Strict validation on @Field annotation on the id property
It has never been correct to use a @Field annotation on the id property unless it was meant to add an additional field, so having a different name than the default id. This assumption is now properly validated for at boot time.
RangeQuery guessing the type from the arguments type
When using the Hibernate Search DSL to creating a RangeQuery, this would automatically create a Numeric range query if the targeted field is mapped using a Numeric Field, or it would use a standard keyword based query when the targeted field is mapped as text.
But when targeting an indexed field which is unknown (not explicitly mapped, so added to the Document via a custom FieldBridge for example), the DSL builder would fall back to keyword ranges in all cases. This is slightly improved now, and it will try guessing the right kind of range query by inspecting the type of the upper/lower parameter. For example if you pass a Long object, it will generate a NumericRangeQuery.
Hibernate Search 5.0.0.CR1
Numbers and Dates now indexed as Numeric Field by default
Hibernate properties of a numeric or date type (Date, Calendar, Integer, int, Long, ..) are no longer transformed by default to String-form keywords but are now encoded into their matching NumericField. You can still achieve the old indexing format by explicitly setting the fieldbriedge, or for example using @DateBridge(encoding=EncodingType.STRING)
Note this change also renamed the DateBridge to org.hibernate.search.bridge.builtin.StringEncodingDateBridge to highlight the specific semantics.
Some implementation classes promoted to integration interface
Some packages and classes which were considered "internal implementation details" have been renamed, as in practice integrating projects would need them. The new category will ensure these are treated as a more stable API in future.
Most of these changes won't affect our user's API, but will probably affect you if you do advanced integrations so here is the full list of changes:
- DirectoryBasedIndexManager was moved package: org.hibernate.search.indexes.impl.DirectoryBasedIndexManager to org.hibernate.search.indexes.spi.DirectoryBasedIndexManager
- InfinispanDirectoryProvider also promoted to an SPI package: org.hibernate.search.infinispan.spi
- org.hibernate.search.engine.impl.SearchMappingBuilder to org.hibernate.search.engine.spi.SearchMappingBuilder
- org.hibernate.search.spi.SearchFactoryBuilder was renamed to org.hibernate.search.spi.SearchIntegratorBuilder
Hibernate Search 5.0.0.Beta3
Two frequently used interfaces have been renamed:
- org.hibernate.search.spi.SearchFactoryIntegrator was renamed to org.hibernate.search.spi.SearchIntegrator
- org.hibernate.search.engine.SearchFactory was renamed to org.hibernate.search.SearchFactory
The SearchFactory was also moved from the Maven module hibernate-search-engine to hibernate-search-orm as it should only be used by the ORM integration. Other integrators should depend exclusively on SearchIntegrator.
Note: this moves the SearchFactory back to the same package as it had in Hibernate Search versions 3.x and 4.x.
Hibernate Search 5.0.0.Beta2
No backwards in-compatible changes
Hibernate Search 5.0.0.Beta1
Apache Lucene 4.10.1
It now requires Apache Lucene 4.10.0 or 4.10.1
Hibernate Search 5.0.0.Alpha5
JMS Backend refactored
The JMS backend was depending to Hibernate ORM; the dependency is removed so that the backend can be used in other environments. A consequence is that implementors of the example class org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController will need to adjust to the new signatures. This class is considered internal and might change frequently, a suggestion rather to extend it is to take it as an example.
Hibernate Search 5.0.0.Alpha4
JDK 7 Required
Now requires Java7 both for development and for runtime.
Apache Lucene 4.8.1
It now requires Apache Lucene 4.8.0 or 4.8.1
As of this release Hibernate Search contains OSGi metadata. This is the first step into providing a fully OSGi ready Search. To avoid split packages (see ), the following changes were applied:
- org.hibernate.search.Environment => org.hibernate.search.cfg.Environment
- org.hibernate.search.SearchFactory => org.hibernate.search.engine.SearchFactory
- org.hibernate.search.SearchException => org.hibernate.search.exception.SearchException
- org.hibernate.search.FullTextFilter => org.hibernate.search.filter.FullTextFilter
- org.hibernate.search.Version => org.hibernate.search.engine.Version
- org.hibernate.search.ProjectionConstants => org.hibernate.search.engine.ProjectionConstants
- org.hibernate.search.spi.MassIndexerFactory => org.hibernate.search.batchindexing.spi.MassIndexerFactory
In addition to Lucene upgrades, it now also requires Infinispan 7.0.0.Alpha4, JGroups 3.5.0.Beta5
Hibernate Search 5.0.0.Alpha2
Mostly a bugfix release with no changes in API or SPI. Some dependencies where cleaned up.
Removal of hibernate-search-analyzers module
The module hibernate-search-analyzers was dropped from the repository and will no longer be included in any release. Technically you don't need it anymore: it has been around for a while only as an empty shell depending on various Solr and Apache Lucene Analyzers: our recommendation is to explicitly depend on the Analyzers you need directly in your projects, which gives you a better control of the dependency graph.
Hibernate Search 5.0.0.Alpha1
The changes in APIs of Hibernate Search packages have been kept to a minimum, still many other important dependencies had major updates so if you where using them you will need to adjust your code.
Apache Lucene 4.6.1
This is a significant change and many APIs of Lucene have changed:
Package name of popular Lucene classes changed
QueryParser(s) changed package: org.apache.lucene.queryParser.QueryParser -> org.apache.lucene.queryparser.classic.QueryParser
many popular Analyzer, TokenFilter, CharFilter implementations moved in a different package.
In our tests we used the following command to do most of the work:
find . -type f -name \*.java -o -name \*.xml | xargs sed -i '' -f ~/sources/Lucene4Migration.sedscript
You'll find the Lucene4Migration.sedscript attached to this page.
The Sorting API changed
Where previously you might have used:
hibQuery.setSort( new Sort( new SortField( "title", SortField.STRING ) ) );
this should be changed to
hibQuery.setSort( new Sort( new SortField( "title", SortField.Type.STRING ) ) );
Dependency to Apache Solr removed
We still provide the same functionality, but most of the utilities we needed from the Apache Solr project where moved into Apache Lucene. Great news for a simplified dependency graph! The downside is that if you where depending on some of these utilities and custom Analyzers directly, you'll need to find the new name.
The org.hibernate.search.engine.service.spi.Service evolved: this is an API for extension points, unless you where integrating the framework with custom services this should not affect you. See the Service SPI javadoc for details.
The enum value SpatialMode.GRID was renamed to the more suited SpatialMode.HASH .
Hibernate Search 4.5
Hibernate Search 4.5.0.CR1
Improved integration with Infinispan: might reject some Infinispan configurations as there are stricter sanity checks on which caches are acceptable to be used for the purpose of storing indexes.
Metadata SPI was polished: if you used the new Metadata API which was introduced during 4.4, you might need to adapt your code.
MassIndexer: tuning option threadsForSubsequentFetching was deprecated and is now being ignored. You probably want to add the value to the threads used for threadsToLoadObjects: this phase now incorporate both stages.
Hibernate Search 4.5.0.Alpha1
Requires (at least) Hibernate ORM 4.3.0.Beta5 and Infinispan 6.0.0.CR1.
No longer compatible with JBoss 7.1: requires WildFly (because of Hibernate ORM, so it could work on previous JBoss versions if you deploy a custom ORM module).
Hibernate Search 4.4
Hibernate Search 4.4.0.Final
No code changes.
Hibernate Search 4.4.0.CR1
The SPI to integrate a custom MassIndexerFactory changed method signature: see HSEARCH-1428
Hibernate Search 4.4.0.Beta1
Dynamic Sharding is introduced, deprecating previous ShardingStrategy.
Entity annotation @Similarity is deprecated: better to use the configuration properties to pick a custom Similarity implementation.
Hibernate Search 4.4.0.Alpha2
No backwards compatibility changes
Upgraded dependencies: Apache Tika to 1.4, Apache Avro to 1.7.5, JGroups 3.3.4.Final, Hibernate Commons Annotations to 4.0.4.Final, Hibernate ORM 4.2.5.Final
Hibernate Search 4.4.0.Alpha1
No backwards compatibility changes
Upgraded dependencies: Hibernate ORM 4.2.3.Final, Infinispan 5.3.0.Final, JGroups 3.3.2
Hibernate Search 4.3.0.Final
No backwards compatibility changes
Hibernate Search 4.3.0.CR1
No backwards compatibility changes
Hibernate Search 4.3.0.Beta1
No mayor compatibility changes: some dependencies updated, some cleaned up (Guava removed).
Hibernate Search 4.3.0.Alpha1
The JGroups backend would previously always behave as an asynchronous backend, since 4.3.0.Alpha1 this can be configured to be synchronous but the default is potentially different than previous versions, as it depends on the worker.execution option: if it's set to sync, the backend will be sync too. And the default of workers.async has always been sync.
Hibernate Search 4.2.0.Final
Hibernate Search 4.2.0.CR1
Apache Lucene 3.6.2
With Hibernate Search 4.2.0.CR1 we now build using - and recommend using - Apache Lucene version 3.6.2; it is still compatible with Lucene 3.6 and 3.6.1 so you have the choice to keep the older version. As always if you upgrade Lucene, it is recommended to rebuild the indexes.
Hibernate Search 4.2.0.Beta2
Improvements on the JMSBackendQueueProcessor broke possible subclasses; it should be easier to extend now to use a custom lookup strategy for the Queues, but still remember this class being in an .impl package it's API might change at any time in future.
IndexingInterceptor applied to MassIndexer
The MassIndexer now applies any IndexingInterceptor you might have enabled on your entities.
ServiceManager SPI changes
The recommended way to use the ServiceManager is now to use BuildContext.getServiceManager(). Methods BuildContext.requestService() and BuildContext.releaseService() are deprecated and will be removed.
Hibernate Search 4.2.0.Beta1
Apache Lucene was updated, as always that means some care is needed as the index might not be completely compatible: we suggest to rebuild the index. This version is not compatible with Apache Lucene 3.5 and previous versions.
Hibernate Search 4.1.1.Final
The method org.hibernate.search.cfg.SearchMapping#getFullTextFilerDefs had a typo and was fixed as SearchMapping#getFullTextFilterDefs.
Before this release the SearchMapping was considered experimental, so the older method wasn't deprecated but just removed.
Hibernate Search 4.1.0.CR3 and 4.1.0.Final
JGroups integration and configuration
JGroups channels where initialized one-per-index. Now a Channel is initialized as a shared service across any index using JGroups master or slave configurations, hence the configuration properties changed.
Configuration options as configurationString and configurationXml, which where embedding the JGroups configuration in the Search configuration, are no longer supported. Use either configurationFile or providedChannel.
Also, configuration is NOT scoped to the index anymore, so the following property is invalid, and will produce a configuration exception at initialization:
Configuration should now use the global service scope:
hibernate.search.services.jgroups.configurationFile = jgroups-configuration.xml
No changes where made in the way an index is configured as a master or slave node, only the JGroups channel configuration attributes where moved.
Hibernate Search 4.1.0.Beta2
The configuration method threadsForIndexWriter is deprecated and not affecting the MassIndexer anywmore. The implementation sends index changes to the same backend as usual, so the number of threads working on the index is determined by the number of backend workers; see worker.thread_pool.size configuration property, which is specific for each index.
Hibernate Search 4.1.0.Beta1
Several versions updated
- Infinispan 5.1.x
- JGroups 3.0.x
- Lucene 3.5
Hibernate Search 4.0.0.Final
Hibernate Search 4.0.0.CR2
Only minor updates and bug fixes.
Hibernate Search 4.0.0.CR1
Only minor updates in components and backwards compatible improvements and bugfixes.
Hibernate Search 4.0.0.Beta2
New jars, Maven modules reorganization
The existing jar (and Maven artifact id) known as hibernate-search was split in two modules: hibernate-search-engine which contains most of the Query logic and all the nice Lucene resource management, and hibernate-search-orm which contains the integration with Hibernate Core and Hibernate EntityManager.
The new hibernate-search-engine does not depend on Hibernate Core, and so can be reused to integrate Apache Lucene in other projects.
If you're migrating a project using hibernate-search it should still work without changes as we created an empty project depending on hibernate-search-orm, or you could depend on hibernate-search-orm.
The hibernate-search-orm depends on both hibernate-search-engine and hibernate-core, optionally on hibernate-entitymanager if you use JPA.
ErrorHandler notifications from MassIndexer failures
Previously you could configure an ErrorHandler to manage eventual exceptions in the backend; this same ErrorHandler will now be notified for errors happening during a MassIndexer run, if any.
Again we keep Search up to date with the latest Apache Lucene release. There where no significant code changes needed, so it's expected to work fine with Lucene 3.3 too if you can't upgrade.
Hibernate Search 4.0.0.Beta1
New parameter list for o.h.s.annotations.Field
Prior to Beta1 the @Field annotation mixed the concept of whether a property is analyzed and whether norms are stored in the index by specifying a single value for the index paramter (NO, TOKENIZED, UN_TOKENIZED and NO_NORMS). The terminology was also using the term tokenizing instead of analyzing and there was no option for analyzed indexing without storing norms.
The new @Field signature is: @Field(index=Index.YES|NO, analyze=Analyze.YES|NO, norms=Norms.YES|NO, ...)
Hibernate Search 4.0.0.Alpha2
The serialization protocol has changed, make sure to purge your JMS or JGroups messages and upgrade you cluster at once.
Mixing Lucene queries and a Criteria query with restrictions (ie where clause) is now supported but query.getResultSize() will raise an exception in this particular case. You must use query.list().size() (or query.getResultList().size()).
Hibernate Core 4.0.0.CR2
We now depend on Hibernate 4.0.0.CR2, make sure to upgrade.
Hibernate Search 4.0.0.Alpha1
This is the first milestone for the next mayor release, hence the changes are quite consistent in the internal architecture, but there are so far no changes in the way the index mapping is defined, so don't be scared by the long list of improvements:
Hibernate Core 4.0.0.CR1
Hibernate Search 4 will depend on Hibernate Core 4; specifically Hibernate Search 4.0.0.Alpha1 was compiled and tested against Hibernate Core 4.0.0.CR1.
As Hibernate Core 4 depends on Java 6, so is now Hibernate Search.
As usual we target the latest Apache Lucene version available at the time of release. When migrating from an older version this means, atop of API changes, that some Analyzers might expose different behaviour: restults from fulltext queries might contain unexpected values or fail to return some matching value.
- We can force Lucene's Analyzers to behave as a limited set of previous releases by using the hibernate.search.lucene_version property.
- You rebuild your index using the MassIndexer. This is always better when possible, as it gives the best compatibility guarantees.
Other upgraded dependencies
For a detailed list we recommend to inspect the pom.xml files, the most notable changes are:
- Logging framework now uses JBoss Logger 3, which delegates as slf4j also did to JDK logging or Log4j but provides better performance and trackable identifiers for errors and warnings. Should make it easier to find references to issues.
- Infinispan integration now depends on Infinispan version 5.0.0.FINAL, with an update JGroups 18.104.22.168.Final.
Getting an IndexReader
An IndexReader for one or more entities can now be obtained directly from the SearchFactory using org.hibernate.search.SearchFactory.openIndexReader(Class<?>...);
Always close an IndexReader obtained in such a way by using the corresponding
These two methods are experimental and likely to be revisited before Hibernate Search 4.0.0 Final.
Previously while it was possible to configure different DirectoryProviders for each index, they had all to share the same backend. This implied that all writing operations had to be handled by either the Lucene backend, or one of the clustering options as JMS or JGroups.
The backend subsystem is now split on a per-index base, and each one can be configured completely independently, including different options for each shard for the same entity:
- Backend type (JMS, JGroups, Lucene, Blackhole).
- Sync/Async options. You can enable a synchronous backend where you need it, and keeping the better performing async option for the other entities which don't strictly need it.
- Executor options (number of threads concurrently writing the index, queue sizes).
- ReaderProvider: different indexes can use a different ReaderProvider implementation.
As usual all these components can be overriden with custom implementations.
Impact on configuration
Previously only DirectoryProvider options where index scoped, while backend options where global. So the previous configuration
Should now be written as:
And of course you can then add overrides on a per index or per-shard base:
The usual strategies are available, but the interface changed and it should be simpler now to implement your own strategy as you'll have to deal with a single index.
A serialization API was introduced; in the past the components from Lucene we needed to Serialize for clustering support implemented Serializable, but this approach is now being dropped in newer releases, so we need now alternative strategies.
In this release we use Apache Avro to serialize the LuceneWork needed to send update operations to clustering backends, before version 4 Final we might make this a pluggable component as usual.
This means that now it's possible to use NumericField even in a clustered environment, which was not serializable.
Exclusive Index enabled by default
The existing option exclusive_index_use defaulted to false in previous releases, this is now true as it significantly improves performance and as a needed step for further optimisations coming in version 4. This also means it's especially important you don't forget to close the SessionFactory or EntityManagerFactory, or the Lucene index will not be unlocked.
Since we're preparing for a mayor release, some other interfaces changed; most importantly we moved in ".impl" packages those interfaces that we consider for internal use, and that application should not import directly.
IndexManager and DirectoryProvider
Previously a Lucene index would be abstracted by it's DirectoryProvider. Direct access to the DirectoryProvider is now discouraged, and resources for each index are organized in an IndexManager, which collects the backend, the ReaderProvider, and the DirectoryProvider if one is used. This change was done so that we will be able to plug in IndexManagers which are not necessarily based on a Lucene Directory contract: all what is needed by the core engine is a way to provide a reference to an IndexReader and a way to apply updates to the index, so now you're welcome to contribute integrations to other Lucene based engines.
Hibernate Search 3.4.0.Final
No changes compared to 3.4.0.CR2
Hibernate Search 3.4.0.CR2
Hibernate Search now requires Lucene 3.1, leveraging all the great improvements from the Lucene team. In terms of Search API nothing changed, Search takes care of hiding the Lucene API changes.
Lucene and Solr changed packaging, some advanced analyzers have been moved into different jars. In case you use Maven to manage your dependencies, this has been taking care for you just depending on the usual hibernate-search-analyzers updating our transitive dependencies; in case you don't use Maven, make sure to locate the new jar names in case some Analyzer is not found on classpath.
max_field_length configuration option ignored
This configuration option is being ignored since it's deprecated in Lucene 3.1. No harm should be done if you don't change your configuration. To properly limit the size of indexed fields use a LimitTokenCountAnalyzer to decorate another analyzer.
Hibernate Search 3.4.0.Alpha1
Field Cache enabled
Lucene's field caching features are now enabled by default on the ProjectionConstants.OBJECT_CLASS field as it is expected that this will improve overall performance. This might require more memory, if you run in performance issues due to memory constraints make sure to read the new reference documentation on how to disable this: Reference documentation.
Hibernate Search 3.3.0.Final
Hibernate Search 3.3.0.Beta3
Sorting full-text queries
Lucene's org.apache.lucene.search.SortField constructor now requires a second parameter to define the kind of desired Sort. Valid values are listed as public constants in SortField, such as SortField.STRING_VAL.
Hibernate Search 3.3.0.Beta2
Some analyzer and filter factories of the framework require additional libriaries (lucene-snowball, lucene-collation, commons-io, commons-codec). These additional libraries are now optional dependencies and have to be added explicitly. Refer to the online documentation to see which analyzer/filter needs which additional dependency.
Hibernate Search 3.3.0.Beta1
Hibernate Search 3.2.0
Hibernate Search 3.2.0.Beta1
Discriminator interface changes
- The getAnanyzerDefinitionName method name in org.hibernate.search.analyzer.Discriminator contained a typo and is now called getAnalyzerDefinitionName.
IndexWriter tuning configuration changes
- Until previous version any configuration option set as indexwriter.transaction.<parameter_name> would also affect the batch version of it, unless indexwriter.batch.<parameter_name> was explicitly set. This was leading to confusion and now to set a batch parameter you have to explicitly set it.
Hibernate Search 3.1.0.GA
Make sure to review the migration guides from the 3.1.x intermediate releases.
Hibernate Search 3.1.0.CR1
- As part of this release we removed calls to deprecated methods and classes in the Lucene 2.4 API. This includes the usage of the deprecated Hits class. This implies that projected Lucene scored won't be normalized anymore.
Hibernate Search 3.1.0.Beta2
- Most APIs have been properly generified. For example, They now accept Class<?> rather than the raw type. You might need to recompile your code and fix a few warnings.
- ReaderProvider has a new method destroy()
- This version makes use of Lucene 2.4.0.
- The Filter definition declaration has changed a bit. Use @FullTextFilterDef.cache now receives FilterCacheModeType enums and is the only cache related configuration. It defaults to cache filter instances and BitSet results.
Hibernate Search 3.1.0.Beta1
- Hibernate Search 3.1 depends on Hibernate Core 3.3, and is integrated with Hibernate Annotations 3.4
- The logging system has moved to slf4j
- The Lucene version must be 2.3 and above
- Optimizations features involving Lucene tuning are now under hibernate.search.[default|<indexname>].indexwriter.[transaction|batch]
- FullTextQuery.BOOST is now deprecated, it always returned 1 and had no concrete usage
- Search.createFullTextSession and Search.createFullTextEntityManager are deprecated and replaced by Search.getFullTextSession and Search.getFullTextEntityManager
- hibernate.search.worker.batch_size is deprecated in favor to the fullTextSession.flushToIndexes();
- Calling fullTextSession.index / purge: raises an exception if the entity is not indexable rather than the previous noop.
- If you implement org.hibernate.search.bridge.FieldBridge or org.hibernate.search.bridge.TwoWayFieldBridge, the method set() has evolved to the following signature void set(String name, Object value, Document document, LuceneOptions luceneOptions)
Hibernate Search 3.0.0.GA
- query.setIndexProjection has been removed (after deprecation), the replaced method is query.setProjection
Hibernate Search 3.0.0.CR1
- DirectoryProvider has a new method start()
- @Text, @Keyword and @Unstored have been removed
Hibernate Search 3.0.0.Beta4
- @Text, @Keyword etc have been deprecated for a while, they will be removed in the next release.
- fullTextQuery.setIndexProjection() has been renamed fullTextQuery.setProjection()
- The default reader strategy is now shared (this should not affect the compatibility though)
- ContextHelper.getSearchFactory is deprecated, prefer fullTextSession.getSearchFactory();
- searchFactory.getDirectoryProvider(Class) is now searchFactory.getDirectoryProviders(Class)
- Lucene Core 2.2 is now used: your index structure will be automatically migrated by Lucene.
Hibernate Search 3.0.0.Beta2
- All org.hibernate.search.query.FullTextQueryImpl casting should be replaced by org.hibernate.search.FullTextQuery casting
- resultSize() has been renamed getResultSize()
- Queries restricting to one entity now use one SQL query rather than depending on @BatchSize() when list() is used, the major impact is that it's going to be faster
- Query query = fullTextSession.createFullTextQuery(luceneQuery, book.class);
- The build phase for Lucene Documents is now done in the beforeCompletion phase of a transaction, making the process insensible to LazyInitializationException. There should be no impact to users that did not hit the bug.