The first beta of Hibernate Search 3.3 is out. We had several goals in mind.

One of them is to morph the project into a more independent piece of software for Infinispan. We have a lot of exciting developments around Infinispan, search and persistence. But that's the subject of another post. On to the meat now.

Hibernate Search query DSL

Probably the most visible feature is the new Hibernate Search query DSL.

Writing Lucene queries is not easy, either you use the query parser limiting yourself to fairly simple queries and manipulating strings or you use the Lucene programmatic query API which is quite verbose and contains a myriad of settings and alternatives.

On top of that, you need to make sure you apply the same magic at query and indexing time: if you don't the index key you look for will not match and you will return no result. This is particularly true in an object world where two transformations occur:

  • the object is transformed in a string via the Hibernate Search FieldBridge
  • the string is transformed into terms via the analyzer

Each property can have different combinations of field bridge and analyzer.

Hibernate Search solves these problems by transparently applying the appropriate FieldBridge and analyzer of a given researched property. It's also built around a fluent API to make queries very easy to write and more importantly easier to read.

QueryBuilder mythQB = searchFactory.buildQueryBuilder().forEntity( Myth.class ).get();

//look for popular modern myths that are not urban
Date twentiethCentury = ...;
Query luceneQuery = mythQB
      .must( mythQB.keyword().onField("description_stem").matching("urban").createQuery() )
      .must( mythQB
        .createQuery() )
      .must( mythQB
        .createQuery() )

This example shows many things:

  • the fluent API in action (you've got to admit that it's more readable than a raw Lucene query)
  • you pass objects and not string representations (Date and number in this case)
  • description_stem uses a stemming analyzer (eg. transforming loving in its root word love): no need to apply it yourself before passing the matching string, the query DSL does that for you.

I will blog in more details about Hibernate Seach query DSL shortly.

Hibernate Core 3.6

This release is compatible with Hibernate Core 3.6 (in Beta3 at the time of writing). A side effect is that manual configuration of the event listeners is no longer necessary even when only using hbm.xml files.


Hardy has been busy designing a statistics API (available from the SearchFactory). It gives you a lot of information about Hibernate Search:

  • average and max time for a Lucene query execution
  • average and max time for the object loading process following a Lucene query execution
  • slowest query
  • number of entities indexed of a given type
  • and many more

Again, a more detailed blog post should come soon.

Integration tests for JTA and Spring

We have added integration tests for both Spring Framework and JTA. On the JTA side, we are testing against Bitronix and JBoss Transactions standalone.

Mutable SearchFactory

While not a public feature yet, Hibernate Search now has the ability to add new entity types on the fly.

From the ground up, we have made sure that Hibernate Search is extremely fast and efficient at runtime. To achieve that we have been using an immutable design for the SearchFactory: we pre-compute and store metadata to make indexing and querying efficient. and that forced us to know the list of indexed entity types ahead of time.

Infinispan, however, does not know necessarily knows the list of entities ahead of time. The new design uses a copy-on-change approach to keep the benefits of the immutable model while offering the ability to add new entities. As a user, you won't notice it but as a framework using Hibernate Search, you will :)

Bug fixes

Of course we also fix bugs :)

Check out the new release on's Maven repository or download the distribution. You can also read the documentation here. Be aware that this version breaks a couple of SPIs, make sure to check the migration guide.

25. Aug 2010, 17:18 CET | Link

The fluent api looks really nice - great work!!

28. Aug 2010, 11:22 CET | Link

I used the new DSL in my code and indeed it is shorter and more readable now. Great work!

I have a two questions I didn't find answers to in the documentation:

1) I want to query for a specific numeric or date value. Is there a way to do it directly instead of using range()...from() ? Should I use keyword()...matching() for that?

2) Is there a way to use the or operator in the DSL? Since I didn't find out how to do it, I used a BooleanQuery for that part.


30. Aug 2010, 15:03 CET | Link

I beg to differ, even though generally I'm a fan of fluent interfaces. Maybe the example would be more expressive, if the subqueries would have been refactored into own variables, but judging from the code as it is quoted above I would prefer SQL or DB4O-like native queries. All these long expressions like keyword().onField("..") matching(".."), .from(3).excludeLimit().to(5), etc. are a huge load of clutter compared to a simple:

where description_stem = "urban" and starred between 4 and 5

Why replace something that simple with something less readable? For the compile time checking? I'd rather have an SQL-syntax checker in my IDE that can be activated with an annotation on the string: @SQL String q = "select ...."; alongside dropping support for raw statements, which are prone to SQL injections. Plus any decent SQL-IDE gets you better support when designing your database queries. I do think that this fluent interface is a waste of time, both for those who implemented and support it (apart from the learning aspect) as for those who will have to deal with it.

30. Aug 2010, 16:54 CET | Link

Hi Gabriel,

1. yes use keyword().onField("creationDate").matching(date); If you have a better name for keyword, I am all ears.

2. The closest to or is should(). There is no strict equivalent of or in Lucene. You've done the right thing.

30. Aug 2010, 17:11 CET | Link

Hi Wanja,

String based queries are good but fail short for the numerous options that full-text queries offer (boost, prefix length, fuzzy factory, analyzer to use etc etc). They also become horrible for more complex queries encompassing several levels of boolean queries.

Hibernate Search query DSL aims at simplifying these kind of more complex and custom queries.

It's a bit like JP-QL vs the Criteria API but with a stronger advantage towards the programmatic approach in the Hibernate Search case.

30. Sep 2010, 02:12 CET | Link

Quick question, does this beta or any future version of Hibernate Search support the ability to configure the indexing via XML instead of annotations? Thanks!

04. Oct 2010, 09:46 CET | Link

Hi Augusto, We do not support XML in a built-in way but we have a much better solution. You can define your metamodel programmatically. Read more here.

22. Nov 2010, 19:01 CET | Link
This is really nice! You mentioned that you'd be blogging more details about the DSL shortly - did I miss it? Just looking for more good info about the DSL.. thanks
13. Dec 2010, 17:39 CET | Link

You did not miss it. I never got the chance to write the entry. The reference documentation has a section dedicated to it though. Let us know if you have questions by opening a JIRA.