Skip to content
Hibernate Search: full-text search for domain model
Branch: master
Clone or download
Latest commit 9fd99a9 Apr 23, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.empty Consider all sources as tests during Sonar analysis in integration te… Sep 12, 2018
backend HSEARCH-3552 Check independently analyzer in Lucene backend Apr 24, 2019
build-config [Jenkins release job] Preparing next development iteration Apr 4, 2019
distribution [Jenkins release job] Preparing next development iteration Apr 4, 2019
jenkins HSEARCH-3051 Consistently use the .aws.signing namespace for AWS sign… Apr 3, 2019
jqassistant HSEARCH-3051 Restore the Elasticsearch AWS integration Apr 3, 2019
legacy HSEARCH-3561 - transpositions is ignored for .keyword().fuzzy() queri… Apr 15, 2019
mapper HSEARCH-3566 Fix reindexing when an association mentioned in an Index… Apr 24, 2019
reports [Jenkins release job] Preparing next development iteration Apr 4, 2019
util HSEARCH-3099 Test indexNullAs positive cases in mapper pojo Apr 19, 2019
.gitignore HSEARCH-3099 Ignore .attach_pid JDK files Apr 17, 2019
.travis.yml HSEARCH-3288 Add the previously missing rule for abstract types Nov 28, 2018
Jenkinsfile HSEARCH-3563 Pass the Elasticsearch version as required when running … Apr 17, 2019
copyright.txt HSEARCH-2612 Add Mincong Huang as an author Oct 25, 2017
dco.txt HSEARCH-2844 Remove requirement for CLA Aug 10, 2017
pom.xml HSEARCH-3099 Document indexNullAs and its parsing Apr 19, 2019

Hibernate Search

Build Status Coverage Status Quality gate Language Grade: Java

Warning: this is Hibernate Search 6

This branch currently contains the code of Hibernate Search version 6, a new major version which is very different from Hibernate Search 5, and is still in its early stages.

If you are looking for the code of the version of Hibernate Search you are currently using, you should try branch 5.11 instead, or any of the older branches.

If you are looking for version 6, then keep in mind that most of the old codebase has been moved to the legacy directory, creating several modules with the same artifact ID.

When importing the Maven modules in Eclipse, you are advised to use the [groupId]:[artifactId] project name template, in order to avoid conflicts. You can distinguish between old and new modules by their group ID: legacy modules use org.hibernate, while newer modules use


Full text search for Java objects

This project provides synchronization between entities managed by Hibernate ORM and full-text indexing backends like Apache Lucene and Elasticsearch.

It will automatically apply changes to indexes, which is tedious and error prone coding work, while leaving you full control on the query aspects. The development community constantly researches and refines the index writing techniques to improve performance.

Mapping your objects to the indexes is declarative, using a combination of Hibernate Search specific annotations and the knowledge it can gather from your existing Hibernate/JPA mapping.

Queries can be defined by any combination of:

  • passing "native" queries directly (org.apache.lucene.Query for the Lucene backend, JSON for the Elasticsearch backend)
  • using our backend-agnostic DSL which generates the appropriate native queries based on the available schema metadata

Query results can include projections to be loaded directly from the index, or can materialize fully managed Hibernate entities loaded from the database within the current transactional scope.

Hibernate Search provides two backends, you can use whichever suits your application best:

  • an embedded Apache Lucene backend, which runs the indexing engine in the same JVM as your application.
  • an Elasticsearch backend, which connects to an external Elasticsearch cluster over the network.

Getting started

NOTE: Hibernate Search 6 is still work in progress. Summary documentation will be made available with the first Alpha release, and will be progressively improved with each subsequent Alpha/Beta release.

All necessary information is available on the Hibernate Search website:

For offline use, distribution bundles downloaded from SourceForge also include the reference documentation for the downloaded version in PDF and HTML format.

Building from source

> git clone
> cd hibernate-search
> mvn clean install

Build options (profiles and properties)


The documentation is based on Asciidoctor. By default only the HTML output is enabled; to also generate the PDF output use:

> mvn clean install -Pdocumentation-pdf

+You can then find the freshly built documentation in the following location:

> ./documentation/target/asciidoctor/en-US


To build the distribution bundle run:

> mvn clean install -Pdocumentation-pdf,dist


The Elasticsearch integration tests run against one single version of Elasticsearch at a time, launching an Elasticsearch server automatically on port 9200. You may redefine the version to use by specifying the right profile and using the property:

> mvn clean install -Pelasticsearch-6.0

The following profiles are available:

  • elasticsearch-5.6 for 5.6.x and later 5.x
  • elasticsearch-6.0 for 6.0.x to 6.6.x
  • elasticsearch-6.7 for 6.7 (the default)
  • elasticsearch-7.0 for 7.x

A list of available versions for can be found on Maven Central.

Alternatively, you can prevent the build from launching an Elasticsearch server automatically and run Elasticsearch-related tests against your own server using the and properties:

> mvn clean install

If you want to run tests against a different Elasticsearch version (6.x for instance), you will still have to select a profile among those listed above, and specify the version:

> mvn clean install -Pelasticsearch-6.0

You may also use authentication:

> mvn clean install

Also, the elasticsearch integration tests can be executed against an Elasticsearch service on AWS. You will need to execute something along the lines of:

> mvn clean install<The full URL of your Elasticsearch endpoint><Your access key><Your secret key><Your AWS region ID>

When building Hibernate Search with new JDKs, you may want to run Elasticsearch with a different JDK than the one used by Maven. This can be done by setting a property (this will only work with the profiles for Elasticsearch 5 and above):

> mvn clean install -Dtest.elasticsearch.java_home=/path/to/my/jdk


New contributors are always welcome. We collected some helpful hints on how to get started on our website at Contribute to Hibernate Search

Source code structure

The project is split in several Maven modules:

  • backend: The backends, i.e. the modules that provide integration to actual indexing services.
    • elasticsearch: A backend that connects to a remote Elasticsearch cluster.
    • lucene: A backend that uses an embedded (same JVM) Lucene instance.
  • build-config: Code-related artifacts like checkstyle and forbiddenapis rules.
  • distribution: Builds the distribution package.
  • documentation: The project documentation.
  • engine: The Hibernate Search engine. This module handles most of the basic integration work (configuration properties, bean instantiation, ...), defines APIs common to every mapper/backend (the Search DSL in particular), and provides the "glue" between mappers and backends.
  • integrationtest: Integration tests for backends (Elasticsearch, Lucene) and mappers (Hibernate ORM), as well as any other technology Hibernate Search integrates with. Here are some notable sub-directories:
    • performance: performance tests.
    • showcase/library: a sample application using Hibernate Search in a Spring Boot environment.
  • legacy: Legacy code from Search 5. This code is not part of the distributed JARs. Parts of it will progressively be re-integrated into the main (Search 6+) code base. Note that compilation and tests in this directory are disabled by default (they are only enabled when the property legacy.skip is set to false). When enabled, Elasticsearch integration test in this directory are executed against Elasticsearch 5.6 by default (instead of 6.0).
  • mapper: The mappers, i.e. the modules that expose APIs to index and search user entities, and do the work of converting between user entities and documents to be indexed.
    • javabean: An experimental (not published) mapper for Java Beans without Hibernate ORM. Mostly useful for tests of the pojo module.
    • orm: A mapper for Hibernate ORM entities.
    • pojo: Contains base classes and APIs that are re-used in other POJO-based mapper.
  • reports: Module built last, producing reports related to test coverage in particular.
  • util: Various modules containing util classes, both for runtime and for tests.


Latest Documentation


Bug Reports

See the HSEARCH project on the Hibernate JIRA instance:

Community Support



This software and its documentation are distributed under the terms of the FSF Lesser GNU Public License (see lgpl.txt).

You can’t perform that action at this time.