Quarkus - Hibernate Search guide

You have a Hibernate ORM-based application? You want to provide a full-featured full-text search to your users? You’re at the right place.

With this guide, you’ll learn how to synchronize your entities to an Elasticsearch cluster in a heart beat with Hibernate Search.We will also explore how you can can query your Elasticsearch cluster using the Hibernate Search API.

Prerequisites

To complete this guide, you need:

• less than 20 minutes

• an IDE

• JDK 1.8+ installed with JAVA_HOME configured appropriately

• Apache Maven 3.5.3+

• Docker

• GraalVM installed if you want to run in native mode

Architecture

The application described in this guide allows to manage a (simple) library: you manage authors and their books.

The entities are stored in a PostgreSQL database and indexed in an Elasticsearch cluster.

Solution

We recommend that you follow the instructions in the next sections and create the application step by step.However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the hibernate-search-elasticsearch-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:1.0.0.CR1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=hibernate-search-elasticsearch-quickstart \
    -DclassName="org.acme.hibernate.search.elasticsearch.LibraryResource" \
    -Dpath="/library" \
    -Dextensions="hibernate-orm-panache, hibernate-search-elasticsearch, resteasy-jsonb, jdbc-postgresql"
cd hibernate-search-elasticsearch-quickstart

This command generates a Maven structure importing the following extensions: Hibernate ORM with Panache, the PostgreSQL JDBC driver, Hibernate Search + Elasticsearch, RESTEasy and JSON-B.

Creating the bare entities

First, let’s create our Hibernate ORM entities Book and Author in the model subpackage.

package org.acme.hibernate.search.elasticsearch.model;
import java.util.List;
import java.util.Objects;
import javax.persistence.CascadeType;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.OneToMany;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
@Entity
public class Author extends PanacheEntity { (1)
    public String firstName;
    public String lastName;
    @OneToMany(mappedBy = "author", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.EAGER) (2)
    public List<Book> books;
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof Author)) {
            return false;
        }
        Author other = (Author) o;
        return Objects.equals(id, other.id);
    }
    @Override
    public int hashCode() {
        return 31;
    }
}

package org.acme.hibernate.search.elasticsearch.model;
import java.util.Objects;
import javax.json.bind.annotation.JsonbTransient;
import javax.persistence.Entity;
import javax.persistence.ManyToOne;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
@Entity
public class Book extends PanacheEntity {
    public String title;
    @ManyToOne
    @JsonbTransient (1)
    public Author author;
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof Book)) {
            return false;
        }
        Book other = (Book) o;
        return Objects.equals(id, other.id);
    }
    @Override
    public int hashCode() {
        return 31;
    }
}

Initializing the REST service

While everything is not yet set up for our REST service, we can initialize it with the standard CRUD operations we will need.

Just copy this content in the LibraryResource file created by the Maven create-project command:

package org.acme.hibernate.search.elasticsearch;
import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.transaction.Transactional;
import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.acme.hibernate.search.elasticsearch.model.Author;
import org.acme.hibernate.search.elasticsearch.model.Book;
import org.jboss.resteasy.annotations.jaxrs.FormParam;
import org.jboss.resteasy.annotations.jaxrs.PathParam;
@Path("/library")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class LibraryResource {
    @Inject
    EntityManager em;
    @PUT
    @Path("book")
    @Transactional
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void addBook(@FormParam String title, @FormParam Long authorId) {
        Author author = Author.findById(authorId);
        if (author == null) {
            return;
        }
        Book book = new Book();
        book.title = title;
        book.author = author;
        book.persist();
    }
    @DELETE
    @Path("book/{id}")
    @Transactional
    public void deleteBook(@PathParam Long id) {
        Book book = Book.findById(id);
        if (book != null) {
            book.author.books.remove(book);
            book.delete();
        }
    }
    @PUT
    @Path("author")
    @Transactional
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void addAuthor(@FormParam String firstName, @FormParam String lastName) {
        Author author = new Author();
        author.firstName = firstName;
        author.lastName = lastName;
        author.persist();
    }
    @POST
    @Path("author/{id}")
    @Transactional
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void updateAuthor(@PathParam Long id, @FormParam String firstName, @FormParam String lastName) {
        Author author = Author.findById(id);
        if (author == null) {
            return;
        }
        author.firstName = firstName;
        author.lastName = lastName;
        author.persist();
    }
    @DELETE
    @Path("author/{id}")
    @Transactional
    public void deleteAuthor(@PathParam Long id) {
        Author author = Author.findById(id);
        if (author != null) {
            author.delete();
        }
    }
}

Nothing out of the ordinary here: it is just good old Hibernate ORM with Panache operations in a standard JAX-RS service.

In fact, the interesting part is that we will need to add very few elements to make our full text search application working.

Using Hibernate Search annotations

Let’s go back to our entities.

Enabling full text search capabilities for them is as simple as adding a few annotations.

Let’s edit the Author entity again to include this content:

package org.acme.hibernate.search.elasticsearch.model;
import java.util.Objects;
import javax.json.bind.annotation.JsonbTransient;
import javax.persistence.Entity;
import javax.persistence.ManyToOne;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.FullTextField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
@Entity
@Indexed (1)
public class Book extends PanacheEntity {
    @FullTextField(analyzer = "english") (2)
    public String title;
    @ManyToOne
    @JsonbTransient
    public Author author;
    // Preexisting equals()/hashCode() methods
}

Now that our books are indexed, we can do the same for the authors.

Open the Author class and include the content below.

Things are quite similar here: we use the @Indexed, @FullTextField and @KeywordField annotations.

There are a few differences/additions though. Let’s check them out.

package org.acme.hibernate.search.elasticsearch.model;
import java.util.List;
import java.util.Objects;
import javax.persistence.CascadeType;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.OneToMany;
import org.hibernate.search.engine.backend.types.Sortable;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.FullTextField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.IndexedEmbedded;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.KeywordField;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
@Entity
@Indexed
public class Author extends PanacheEntity {
    @FullTextField(analyzer = "name") (1)
    @KeywordField(name = "firstName_sort", sortable = Sortable.YES, normalizer = "sort") (2)
    public String firstName;
    @FullTextField(analyzer = "name")
    @KeywordField(name = "lastName_sort", sortable = Sortable.YES, normalizer = "sort")
    public String lastName;
    @OneToMany(mappedBy = "author", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.EAGER)
    @IndexedEmbedded (3)
    public List<Book> books;
    // Preexisting equals()/hashCode() methods
}

Analyzers and normalizers

Introduction

Analysis is a big part of full text search: it defines how text will be processed when indexing or building search queries.

The role of analyzers is to split the text into tokens (~ words) and filter them (making it all lowercase and removing accents for instance).

Normalizers are a special type of analyzers that keeps the input as a single token.It is especially useful for sorting or indexing keywords.

There are a lot of bundled analyzers but you can also develop your own for your own specific purposes.

You can learn more about the Elasticsearch analysis framework in the Analysis section of the Elasticsearch documentation.

Defining the analyzers used

When we added the Hibernate Search annotations to our entities, we defined the analyzers and normalizers used.Typically:

@FullTextField(analyzer = "english")

@FullTextField(analyzer = "name")

@KeywordField(name = "lastName_sort", sortable = Sortable.YES, normalizer = "sort")

We use:

• an analyzer called name for person names,

• an analyzer called english for book titles,

• a normalizer called sort for our sort fields

but we haven’t set them up yet.

Let’s see how you can do it with Hibernate Search.

Setting up the analyzers

It is an easy task, we just need to create an implementation of ElasticsearchAnalysisConfigurer(and configure Quarkus to use it, more on that later).

To fulfill our requirements, let’s create the following implementation:

package org.acme.hibernate.search.elasticsearch.config;
import org.hibernate.search.backend.elasticsearch.analysis.ElasticsearchAnalysisConfigurer;
import org.hibernate.search.backend.elasticsearch.analysis.model.dsl.ElasticsearchAnalysisDefinitionContainerContext;
public class AnalysisConfigurer implements ElasticsearchAnalysisConfigurer {
    @Override
    public void configure(ElasticsearchAnalysisDefinitionContainerContext context) {
        context.analyzer("name").custom() (1)
                .tokenizer("standard")
                .tokenFilters("asciifolding", "lowercase");
        context.analyzer("english").custom() (2)
                .tokenizer("standard")
                .tokenFilters("asciifolding", "lowercase", "porter_stem");
        context.normalizer("sort").custom() (3)
                .tokenFilters("asciifolding", "lowercase");
    }
}

Adding full text capabilities to our REST service

In our existing LibraryResource, we just need to inject the following methods (and add a few imports):

    @Transactional (1)
    void onStart(@Observes StartupEvent ev) throws InterruptedException { (2)
        // only reindex if we imported some content
        if (Book.count() > 0) {
            Search.session(em)
                    .massIndexer()
                    .startAndWait();
        }
    }
    @GET
    @Path("author/search") (3)
    @Transactional
    public List<Author> searchAuthors(@QueryParam String pattern, (4)
            @QueryParam Optional<Integer> size) {
        return Search.session(em) (5)
                .search(Author.class) (6)
                .predicate(f ->
                    pattern == null || pattern.trim().isEmpty() ?
                            f.matchAll() : (7)
                            f.simpleQueryString()
                                .fields("firstName", "lastName", "books.title").matching(pattern) (8)
                )
                .sort(f -> f.field("lastName_sort").then().field("firstName_sort")) (9)
                .fetchHits(size.orElse(20)); (10)
    }

Configuring the application

As usual, we can configure everything in the Quarkus configuration file, application.properties.

Edit src/main/resources/application.properties and inject the following configuration:

quarkus.ssl.native=false (1)
quarkus.datasource.url=jdbc:postgresql:quarkus_test (2)
quarkus.datasource.driver=org.postgresql.Driver
quarkus.datasource.username=quarkus_test
quarkus.datasource.password=quarkus_test
quarkus.hibernate-orm.database.generation=drop-and-create (3)
quarkus.hibernate-orm.sql-load-script=import.sql (4)
quarkus.hibernate-search.elasticsearch.version=7 (5)
quarkus.hibernate-search.elasticsearch.analysis.configurer=org.acme.hibernate.search.elasticsearch.config.AnalysisConfigurer (6)
quarkus.hibernate-search.elasticsearch.automatic-indexing.synchronization.strategy=searchable (7)
quarkus.hibernate-search.elasticsearch.index-defaults.lifecycle.strategy=drop-and-create (8)
quarkus.hibernate-search.elasticsearch.index-defaults.lifecycle.required-status=yellow (9)

Creating a frontend

Now let’s add a simple web page to interact with our LibraryResource.Quarkus automatically serves static resources located under the META-INF/resources directory.In the src/main/resources/META-INF/resources directory, overwrite the existing index.html file with the content from thisindex.html file.

Automatic import script

For the purpose of this demonstration, let’s import an initial dataset.

Let’s create a src/main/resources/import.sql file with the following content:

INSERT INTO author(id, firstname, lastname) VALUES (nextval('hibernate_sequence'), 'John', 'Irving')
INSERT INTO author(id, firstname, lastname) VALUES (nextval('hibernate_sequence'), 'Paul', 'Auster')
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'The World According to Garp', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'The Hotel New Hampshire', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'The Cider House Rules', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'A Prayer for Owen Meany', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'Last Night in Twisted River', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'In One Person', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'Avenue of Mysteries', 1);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'The New York Trilogy', 2);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'Mr. Vertigo', 2);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'The Brooklyn Follies', 2);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'Invisible', 2);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), 'Sunset Park', 2);
INSERT INTO book(id, title, author_id) VALUES (nextval('hibernate_sequence'), '4 3 2 1', 2);

Preparing the infrastructure

We need a PostgreSQL instance and an Elasticsearch cluster.

Let’s use Docker to start one of each:

docker run -it --rm=true --name elasticsearch_quarkus_test -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.4.0

docker run --ulimit memlock=-1:-1 -it --rm=true --memory-swappiness=0 --name postgresql_quarkus_test -e POSTGRES_USER=quarkus_test -e POSTGRES_PASSWORD=quarkus_test -e POSTGRES_DB=quarkus_test -p 5432:5432 postgres:11.3

Time to play with your application

You can now interact with your REST service:

• start Quarkus with ./mvnw compile quarkus:dev

• open a browser to http://localhost:8080/

• search for authors or book titles (we initialized some data for you)

• create new authors and books and search for them too

As you can see, all your updates are automatically synchronized to the Elasticsearch cluster.

Building a native executable

You can build a native executable with the usual command ./mvnw package -Pnative.

Running it is as simple as executing ./target/hibernate-search-elasticsearch-quickstart-1.0-SNAPSHOT-runner.

You can then point your browser to http://localhost:8080/ and use your application.

Further reading

If you are interested into learning more about Hibernate Search 6, the Hibernate team has some documentation in the works.

It is still work in progress but covers all main concepts and features,so it can guide you in your exploration.

FAQ

Why Hibernate Search 6 (and not a fully supported version)?

To optimize the Hibernate Search bootstrap for Quarkus, the Hibernate team had to reorganize things a bit (collect the metadata offline, start the Elasticsearch client later…​).

This couldn’t be done in the 5.x code base so we decided to go with the in-progress Hibernate Search 6.

Can I really use it?

While Hibernate Search 6 is still at Beta stage, the code is of production quality and can be relied on.

What we don’t guarantee is that there might be API changes along the way to the final release of Hibernate Search 6 and you might have to adapt your code.

If it is not a major issue for you, then sure you can use it.

Why Elasticsearch only?

Hibernate Search supports both a Lucene backend and an Elasticsearch backend.

In the context of Quarkus and to build microservices, we thought the latter would make more sense.Thus we focused our efforts on it.

We don’t have plans to support the Lucene backend in Quarkus for now.

Hibernate Search Configuration Reference

Configuration property fixed at build time - ️ Configuration property overridable at runtime