Red Hat

In Relation To Hibernate Search

In Relation To Hibernate Search

When creating a bug report for any project within the Hibernate family, it’s extremely helpful (and, frankly, required) to have an adequate test case available. This is obviously important to make reproducing the issue as easy as possible. But it’s also vital longer-term. Nearly every bug fix should include a regression test, which is frequently based on the original reproducer (sometimes, it’s the reproducer, verbatim).

To help create useful test cases, we’re opening up a repo with various templates. Please see the READMEs in each project’s subdir for more info: Hibernate Test Case Templates

As a starting point, the repo contains two templates for ORM:

  • ORMUnitTestCase: By far, this one’s the most helpful. ORM includes a built-in unit test framework that does much of the heavy lifting for you. All that’s required is your entities, logic, and any necessary settings. Since we nearly always include a regression test with bug fixes, providing your reproducer using this method simplifies the process. We can then directly commit it, without having to mold it in first. What’s even better? Fork hibernate-orm itself, add your test case directly to a module’s unit tests (using the template class), then submit it as a PR!

  • ORMStandaloneTestCase: This template is standalone and will look familiar. It simply uses a run-of-the-mill ORM setup. Although it’s perfectly acceptable as a reproducer, lean towards ORMUnitTestCase whenever possible.

The eventual goal is to also include templates for Validator, Search, and OGM.

As always, this is open source for a reason! If the templates can be improved in any way, please let us know (either through our JIRA instance or through GitHub Issues). Better yet, send us a pull request!

Hibernate Search 5.3.0.Final now available!

Posted by Sanne Grinovero    |    Jun 10, 2015    |    Tagged as Hibernate Search

As suggested last week, today we released Hibernate Search version 5.3.0.Final.

Compared to the previous candidate release, the only changes are some minor clarifications in the documentation.

   <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-search-orm</artifactId>
      <version>5.3.0.Final</version>
   </dependency>

Faceting API changes

The new great faceting integration comes at a small migration cost: remember you now need to use the new @Facet annotation as explained in the the example of the previous post.

What's next?

Barring some maintenance needs on this branch 5.3, we have no plans of other Hibernate Search releases to target Hibernate ORM 4.3.x. The focus is now on Hibernate 5 compatibility.

  • Artefact jars are available on Maven Central under the GAV org.hibernate:hibernate-search-orm:5.3.0.Final
  • Tarballs and zip bundles can be downloaded from our website
  • Feedback is welcome on the forums and emails, IRC

For those of you using Hibernate ORM version 5.0.0.CR1, you can now use the freshly released Hibernate Search 5.4 version 5.4.0.Alpha1.

What's new

Absolutely nothing! This Hibernate Search version is identical in terms of features and API to version 5.3.0.CR1: this should make it easier for you all to upgrade the Hibernate ORM libraries (hibernate-core, hibernate-entitymanager,..) without the distraction of changes because of Hibernate Search: focus on the changes you'll need to apply because of the major version upgrade of Hibernate (if any, as it's not too complex at all).

WildFly compatibility and JBoss Modules

With every release of Hibernate Search we normally also release a set of modules to run the latest version of it on WildFly, but in this case since the updated Hibernate ORM 5 integrations for WildFly have yet to be released, we skipped this step. Fear not, the WildFly integration will be finished soon and we'll then resume releasing such module packs as usual. Not least, this very same version of Hibernate Search will soon be available in WildFly 10, so the modules missing today won't actually be needed at all.

This is a great time to try Hibernate 5

While the latest polish is performed on Hibernate 5, we're all looking forward for feedback from you. It is likely that some more changes will be done, but we consider it good enough already to not expect any regression so please try it and let us know! We're at that sweet spot in which you can still propose changes without the chains of strong API compatibility requirements, but good enough for you to not be wasting time on a quickly changing target.

Versions reminder

This version of Hibernate Search requires:

  • Hibernate ORM 5.0.0.CR1
  • Apache Lucene 4.10.x
  • Java SE 7

Our rules and conventions for versions and compatibility are documented here on the GitHub Wiki.

  • Artefact jars are available on Maven Central under the GAV org.hibernate:hibernate-search-orm:5.4.0.Alpha1
  • Zip and tar bundles are available via our website
  • Feedback is welcome on the forums and emails, IRC

Tonight we released Hibernate Search version 5.3.0.CR1 (candidate release).

We consider this stable, and besides some pending documentation improvements, we'll re-publish the same implementation as 5.3.0.Final in ten days. Last chance to provide feedback! Please try it out.

Brand-new but proven faceting technology

The technology which Hibernate Search uses under the hood to implement this amazing feature has been improved and polished in various years by the Apache Lucene team. So far Hibernate Search has been using an old and proven technique but this had several limitations.

We believe the new implementation is now mature enough for our users too, and probably should have switched earlier if we didn't have other subjects to attack.

From a user's perspective, there are less limitations and the API is the same, with one migration catch: please remember you now need to opt-in the fields you want to use for faceting explicitly! For that, use the @Facet annotation as shown in the example of the previous post and in the Faceting reference documentation.

What's next?

Our immediate focus is to release am experimental tag to support Hibernate ORM 5: remember, Hibernate Search versions from 4.5 up to (and including) 5.3 are only compatible with Hibernate ORM versions 4.3.x.

Of course, we're also looking forward for feedback and will try and schedule any issues you encounter on the latest versions to be fixed ASAP. Suggestions and contributions are welcome as well!

  • Artefact jars are available on Maven Central under the GAV org.hibernate:hibernate-search-orm:5.3.0.CR1
  • Zip and tar bundles are available via our website
  • Feedback is welcome on the forums and emails, IRC

Following on the heels of 5.2.0.Final, Hibernate Search 5.3.0.Beta1 is now out. This time the faceting engine got an overhaul.

This work was long overdue, because there were several shortcomings with the existing implementation. For example, there were limitations with *ToMany associations. Also, the implementation was based on a custom Lucene Collector making use of the FieldCache API. FieldCache will be removed in Lucene 5, so updating the faceting API was also a requirement for upgrading to Lucene 5 in the near future.

What has changed? Actually not much when it comes to the API Hibernate Search exposes. You still create your FacetingRequest using QueryBuilder.facet().... You then enable the facet search by passing it to the FacetManager from which you also then retrieve the list of Facet instances after the query was executed. All this is unchanged and documented in the online documentation.

A few things have changed though. Most notably, you will need to tell Hibernate Search now which properties are used for faceting. You do so by adding @Facet (resp. @Facets) to these properties. The reason for this is, that under the hood the implementation is now based on Lucene's dynamic faceting capabilties. For this to work, we need to index the facet values using the appropriate DocValues type (SortedSetDocValuesFacetField, NumericDocValuesField or DoubleDocValuesField). Below we see the use of the @Facet(s) annotation:

    @Indexed
    public class Quux {
        @DocumentId
        private Integer id;
        
        @Field(analyze = Analyze.NO),
        @Facets({
                @Facet,
                @Facet(name = "string_facet_value", encoding = FacetEncodingType.STRING)
        })
        private double value;
    }
Notice that in this example the value field is configured with two facet annotations. The reason is, that per default numbers will be stored using numeric DocValues types (NumericDocValuesField and DoubleDocValuesField), whereas all other types use string based SortedSetDocValuesFacetField. Numeric values can then only be used with a range facet whereas discrete facets require string values. In the case where you want to use discrete faceting on a numeric field (for example if the field only contains a fixed number of possible values) FacetEncodingType.STRING needs to be used.

This is inline with the fact that Hibernate Search 5.x indexes numbers now per default numerically (see this blog).

A final caveat - there was a change in the default behaviour of includeZeroCounts as part of a facet request. The default was to include zero counts, but has changed now to not include it. Instead it must be explicitly specified (calculating zero counts for discrete facets comes with a performance penalty!):

    FacetingRequest request = queryBuilder( Car.class ).facet()
            .name( "quuxFacetRequest" )
            .onField( "string_facet_value" )
            .discrete()
            .includeZeroCounts( true )
            .createFacetingRequest();

Release info for Hibernate Search 5.3.0.Beta1

  • Full change log is available on JIRA
  • Artefact jars are available on Maven Central under the GAV org.hibernate:hibernate-search-orm:5.3.0.Beta1
  • Zip and tar bundles on SourceForge

Happy faceting!

The latest stable release of Hibernate Search, version 5.2.0.Final, is now available in Maven mirrors and as traditional downloads from Sourceforge.

Multi-tenancy integration

The most visible new feature is that it now transparently integrates with Hibernate ORM's support for multi-tenancy. The Hibernate Search documentation on multi-tenancy describes how using this near feature from Hibernate ORM will affect the content of your indexes and how it is transparently applied to any Query operation.

The good news is that, while you might want to read the documentation to better understand how it works exactly, the documentation is short as it's all pretty much automatic: full-text queries are automatically filtered on the tenant identifier, providing the same semantics as you would with any other kind of query.

Other improvements

This version incorporates many more improvements which we won't list in detail here. As usual you might find some benefits in the areas of performance and efficiency, improved javadocs, improved OSGi support. The Query builder DSL is improving thanks to the ever increasing great feedback. Keep it coming, we'll keep improving!

A reminder on the requirements for this version

  • Java 7 or later
  • Hibernate versions 4.3.x
  • Apache Lucene versions 4.10.x

What's coming next?

We've been working on a fully renewed Faceting support. Version 5.3.0.Beta1 will be available very soon as well, and include all of this work. Brace yourself though! While it will be API compatible, it will require some changes to your mapping: watch this space.

Get the update!

Everything you need is available on Hibernate Search's web site. Download the full distribution from here, or get it from Maven Central, and don't hesitate to reach us in our forums.

Last night we released Hibernate Search 5.2.0.Beta1, and as many users requested we worked on Multi-Tenancy support.

Multi-tenancy

This feature was available since some time in Hibernate ORM, but while Hibernate Search would not prevent you to use it, it wouldn't apply the same strict isolation on full-text queries. This is all implemented now, and is super easy to use.

How to use it

It's not different than any usage of Hibernate ORM's multi-tenancy. After you open a tenant-aware 'Session', changes will be tagged as belonging to a specific tenant automatically. When performing a full-text query, you'll only get results from the current tenant. When rebuilding the index using the MassIndexer, it will rebuild only the index from the current tenant. When performing a purgeAll operation, it will only delete entries which belong to the current tenant.

Implementation and Sharding considerations

In this implementation, as suggested by some of you we didn't create a fully independent index for each tenant, but each Document in the index gets tagged by the tenantid.

I am wondering if we should also implement a variation in which we keep each tenant's data into a fully independent index: please let us know what you think about that. The current approach of a single index works better if you have a very high amount of tenants, as there are practical limits in how many indexes can be managed. Another benefit of the current approach, is that you can easily plug in a clever custom sharding implementation; by working on a modulo approach among a list of tenants, you can tune it for a reasonable level of separation without necessarily having as many indexes as tenants.

Performance on polymorphic entity loading

The performance improvement highlight of the month goes to a revisited strategy on our internal usage of criterias when loading polymorphic results. If you were loading full-text results from a non-trivial class hierarchy you might notice a sweet performance improvement. For more details see HSEARCH-1793.

MassIndexer now supporting a Cancel operation

The async variation of the MassIndexer returns a Future, but this didn't implement the cancel operation. Many thanks to Yoann Gendre for implementing it!

Other improvements

For the list of minor improvements, please refer to the changelog.

Get the update!

Everything you need is available on Hibernate Search's web site. Download the full distribution from here, or get it from Maven Central, and don't hesitate to reach us in our forums.

We released Hibernate Search 5.1.1.Final, a micro update for version 5.1: our latest best release ever which we described early this month.

Special thanks to:

Török László for fixing a subtle bug in NullEncodingTwoWayFieldBridge

Russell Dickenson for fixing many typos in the documentation

Thach Hoang for improving javadoc of the @Spatial annotation

Besides the above fixes, a good reason to publish this release already was HSEARCH-1824. This problem won't affect you as Hibernate user but was a blocker to update the Infinispan Query engine to Hibernate Search 5.1.x.

Remember you can annotate any Java pojo - even not Hibernate entities - and have them indexed and queried as usual when you store them in Infinispan.

Get updated!

Everything you need is available on Hibernate Search's web site. Download the full distribution from here, or get it from Maven Central, and don't hesitate to reach us in our forums.

Stackoverflow

If you prefer to use stackoverflow.com, please use the tag hibernate-search. And if you have a moment to help other users, some please consider registering to the hibernate-search tag to help us answering all the questions.

If you are new to Hibernate Search, best is to start with our getting started guide. And remember: feedback, comments and/or pull-requests are welcome on the website too.

Hibernate Search 5.1

Posted by Sanne Grinovero    |    Mar 4, 2015    |    Tagged as Hibernate Search

Now that feedback is coming about our great 5.0 release, it's time to publish quite a maintenance version as we have a long list of improvements already! So today we release Hibernate Search 5.1.0.Final.

Performance improvements

The indexing engine learned yet another smart trick, and is going to generate more efficient delete and update operations in case you have a non-trivial hierarchy of entities being mapped. See also HSEARCH-1767 for more details. This might not affect you at all, or it might give you a very significant performance boost!

Also affecting performance, the caching code for Filters improved and this might result in a higher cache hit ratio.

Many usability improvements

  • It is no longer required to provide a key object for parameterized Filters (we'll figure it out automatically). (HSEARCH-295)
  • You can now use annotations to declare Filters and Analyzers on packages or super classes! After all, these are global. (HSEARCH-1763, HSEARCH-633)
  • When booting programmatically, you can now inject an instance of an ErrorHandler (HSEARCH-1624)
  • The programmatic configuration API was improved by adding some missing methods

Projection: bugfixes

There was a bug in projecting values of embeddable types which could strike occasionally, as it would trigger only on some specific iterations of the metadata, which is unsorted so it could manifest only occasionally. This is fixed now as HSEARCH-1786.

Many thanks to Rustem Sagimbekov, Marc Schipperheyn and Ildar Mussin for reporting it and helping me diagnose the problem.

Multi-tenancy

Some users have recently been trying to use Hibernate Search combined with Hibernate ORM's multi-tenancy features. We have to admit this wasn't tested! We added a warning in the documentation, as some more work is going to be needed to make for a flawless integration experience.

There was one blocker preventing people to use the MassIndexer HSEARCH-1649 with multi-tenancy, which is fixed now. So while there are still some limitations documented here, you should be able to move forward. Please let us know if more changes are needed (on top of the known limitations, which are easy to work around for now).

OSGi improvements

With 5.0 we published our first experimental support for depoying in OSGi, and it's maturing quickly thanks to all your feedback! Thanks to Gustavo Nalle and Andy Phillips for the latest suggestions and improvements.

Dropped

The optional serialization module based on plain standard Java serialization was removed. Please use hibernate-search-serialization-avro, which has always been the better implementation. If you had strong reasons to love the plain java implementation, let us know.

Components upgrades

  • Apache Lucene released 4.10.4
  • Infinispan upgraded to 7.1.1

Get it now!

Everything you need is available on Hibernate Search's web site. Download the full distribution from here. And don't hesitate to reach us in our forums.

Stackoverflow

If you prefer to use stackoverflow.com, please use the tag hibernate-search. And if you have a moment to help other users, some please consider registering to the hibernate-search tag to help us answering all the questions.

If you are new to Hibernate Search, best is to start with our getting started guide. And remember: feedback, comments and/or pull-requests are welcome on the website too.

Some more Hibernate Search 5

Posted by Sanne Grinovero    |    Jan 12, 2015    |    Tagged as Hibernate Search

After the great news in December of the release of Hibernate Search 5.0.0.Final and the first stable (.Final) release of Hibernate OGM, we plan to keep updates coming regularly.

So today we introduce:

  • Hibernate Search 5.0.1.Final
  • Hibernate Search 4.5.3.Final

Both are considered stable; as expected for micro maintenance there was no need to update neither documentation nor the migration guide.

What's new in version 5.0.1.Final

  • updated to latest stable Hibernate ORM 4.3.8.Final
  • updated to latest stable Apache Lucene 4.10.3
  • improved some logging messages to be able to better help some users

What's new in version 4.5.3.Final

  • backported some backend changes like HSEARCH-1770, mostly useful to third party integrators such as Infinispan Query to improve their indexing efficiency.

WildFly 9 is coming

The source code of WildFly was updated to include our latest Hibernate Search 5. Looking forward to the final release of this super popular application server, as you won't have to download the Hibernate Search 5 dependencies separately!

How to get it

Everything you need is available on Hibernate Search's web site. Download the full distribution from here. And don't hesitate to reach us in our forums.

Stackoverflow

If you prefer to use stackoverflow.com, please use the tag hibernate-search. And if you have a moment to help other users, some please consider registering to the hibernate-search tag to help us answering all the questions.

If you are new to Hibernate Search, best is to start with our getting started guide. And remember: feedback, comments and/or pull-requests are welcome on the website too.

Next talk: JBUG London

Please remember I'll be talking about Hibernate Search 5 this Wednesday the 14th of January in London. There will be pizza, beers, and pub time to discuss anything related to Search.

back to top