Hibernate Search

Description

Hibernate Search automatically extracts data from Hibernate ORM entities to push it to local Apache Lucene indexes or remote Elasticsearch indexes.

It features:

• Declarative mapping of entity properties to index fields, either through annotations or a programmatic API.
• On-demand mass indexing of all entities in the database, to initialize the indexes with pre-existing data.
• On-the-fly automatic indexing of entities modified through a Hibernate ORM session, to always keep the indexes up-to-date.
• A Search DSL to easily build full-text search queries and retrieve the hits as Hibernate ORM entities.
• And more: configuration of analyzers, many different predicates and sorts in the Search DSL, spatial support. search queries returning projections instead of entities, aggregations, advanced customization of the mapping using bridges, ...

For example, map your entities like this:

@Entity
// This entity is mapped to an index
@Indexed
public class Book {

    // The entity ID is the document ID
    @Id
    @GeneratedValue
    private Integer id;

    // This property is mapped to a document field
    @FullTextField(analyzer = "english")
    private String title;

    @ManyToMany
    // Authors will be embedded in Book documents
    @IndexedEmbedded
    private Set<Author> authors = new HashSet<>();

    // Getters and setters
    // ...
}

@Entity
public class Author {

    @Id
    @GeneratedValue
    private Integer id;

    // This property is mapped to a document field
    @FullTextField(analyzer = "name")
    private String name;

    @ManyToMany(mappedBy = "authors")
    private Set<Book> books = new HashSet<>();

    public Author() {
    }

    // Getters and setters
    // ...
}

Index existing data like this:

SearchSession searchSession = Search.session( entityManager );
MassIndexer indexer = searchSession.massIndexer( Book.class );
indexer.startAndWait();

Automatic indexing does not require any change to code based on JPA or Hibernate ORM:

Author author = new Author();
author.setName( "Isaac Asimov" );

Book book = new Book();
book.setTitle( "The Caves Of Steel" );
book.getAuthors().add( author );
author.getBooks().add( book );

entityManager.persist( author );
entityManager.persist( book );

And search like this:

SearchResult<Book> result = Search.session( entityManager )
        .search( Book.class )
        .where( f -> f.match()
                .fields( "title", "authors.name" )
                .matching( "Isaac" )
        )
        .fetch( 20 );

long totalHitCount = result.getTotalHitCount();
List<Book> hits = result.getHits();

License

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

Getting started

A getting started guide is available in the reference documentation.

Fore more information, refer to the Hibernate Search website:

• Available versions and compatibility matrix
• Reference documentation for all versions (current and past)

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

Contact

Latest Documentation

See http://hibernate.org/search/documentation/.

Bug Reports

See the HSEARCH project on the Hibernate JIRA instance: https://hibernate.atlassian.net/browse/HSEARCH.

Community Support

See http://hibernate.org/community/.

Contributing

New contributors are always welcome. See CONTRIBUTING.md to get started.

Building from source

git clone git@github.com:hibernate/hibernate-search.git
cd hibernate-search
mvn clean install

Build options (profiles and properties)

Documentation

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

Distribution

To build the distribution bundle run:

mvn clean install -Pdocumentation-pdf,dist

Elasticsearch

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 test.elasticsearch.connection.version property:

mvn clean install -Pelasticsearch-6.0 -Dtest.elasticsearch.connection.version=6.0.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.2.x
• elasticsearch-6.3 for 6.3.x
• elasticsearch-6.4 for 6.4.x to 6.6.x
• elasticsearch-6.7 for 6.7 and later 6.x
• elasticsearch-7.0 for 7.x (the default)

A list of available versions for test.elasticsearch.connection.version 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 test.elasticsearch.connection.hosts properties:

mvn clean install -Dtest.elasticsearch.connection.hosts=http://localhost:9200

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 -Dtest.elasticsearch.connection.version=6.0.0 -Dtest.elasticsearch.connection.hosts=http://localhost:9200

You may also use authentication:

mvn clean install -Dtest.elasticsearch.connection.hosts=https://localhost:9200 -Dtest.elasticsearch.connection.username=ironman -Dtest.elasticsearch.connection.password=j@rV1s

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 -Dtest.elasticsearch.connection.hosts=<The full URL of your Elasticsearch endpoint> -Dtest.elasticsearch.connection.aws.signing.access_key=<Your access key> -Dtest.elasticsearch.connection.aws.signing.secret_key=<Your secret key> -Dtest.elasticsearch.connection.aws.signing.region=<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.run.java_home=/path/to/my/jdk

JQAssistant

You can request static analysis and sanity checks with the jqassistant profile. Tests do not need to be run for these checks.

mvn clean install -Pjqassistant -DskipTests

To also check cyclic dependencies between packages, use -Djqassistant.groups=default,cycles. Cyclic dependency analysis is costly and may add significant overhead to the build: at least 10 seconds, maybe one minute or more depending on your setup.

mvn clean install -Pjqassistant -DskipTests -Djqassistant.groups=default,cycles

You can also inspect the created Neo4j datastore after a build, provided that build had the jqassistant profile enabled:

mvn jqassistant:server -Pjqassistant-server -pl reports

The Neo4j web UI will be accessible from http://localhost:7474/.

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.
• 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-base: 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.