バージョン:

Hibernate Search ガイド

前提条件
アーキテクチャ
ソリューション
Mavenプロジェクトの作成
ただのエンティティの作成
RESTサービスの初期化
Hibernate Searchアノテーションの使用
- Programmatic mapping
アナライザーとノーマライザー
- はじめに
- 使用するアナライザーの定義
- アナライザーのセットアップ
RESTサービスに全文検索機能を追加
アプリケーションの設定
- 開発サービス（コンフィグレーション・フリー・データベース）
フロントエンドの作成
自動インポートスクリプト
アプリケーションで遊ぶ時間
OpenSearch対応
複数の永続化ユニット
- 複数の永続化ユニットを設定
- モデルクラスの永続化ユニットへのアタッチメント
CDI統合
ネイティブ実行可能ファイルの構築
オフライン起動
アウトボックスポーリングによる調整
AWSのリクエストの署名
参考資料
FAQ
- なぜElasticsearchだけなのか?
Hibernate Search 設定リファレンス
- 主な構成
- アウトボックスポーリングとの連携の設定

Hibernate ORMベースのアプリケーションを持ってますか？フル機能の全文検索をユーザーに提供したいですか？あなたは正しいドキュメントを読んでいます。

このガイドでは、Hibernate Search を使用して、エンティティを Elasticsearch または OpenSearch クラスタに瞬時に同期させる方法を学びます。また、Hibernate Search API を使用して Elasticsearch または OpenSearch クラスタにクエリを実行する方法についても説明します。

前提条件

このガイドを完成させるには、以下が必要です:

ざっと 20 minutes
IDE
JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること
Apache Maven 3.9.3
動作するコンテナランタイム(Docker, Podman)
使用したい場合は、 Quarkus CLI
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、適切に設定していること

アーキテクチャ

このガイドに記載されているアプリケーションは、(シンプルな) 図書館を管理することができます:あなたは、著者とその本を管理します。

エンティティはPostgreSQLデータベースに格納され、Elasticsearchクラスターにインデックスされます。

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.git 、アーカイブをダウンロードします。

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

提供されるソリューションには、テストやテストのインフラストラクチャなど、いくつかの追加要素が含まれています。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します:

コマンドラインインタフェース

quarkus create app org.acme:hibernate-search-orm-elasticsearch-quickstart \
    --extension='hibernate-orm-panache,jdbc-postgresql,hibernate-search-orm-elasticsearch,resteasy-reactive-jackson' \
    --no-code
cd hibernate-search-orm-elasticsearch-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.4.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=hibernate-search-orm-elasticsearch-quickstart \
    -Dextensions='hibernate-orm-panache,jdbc-postgresql,hibernate-search-orm-elasticsearch,resteasy-reactive-jackson' \
    -DnoCode
cd hibernate-search-orm-elasticsearch-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

If using cmd, (don’t use backward slash \ and put everything on the same line)
If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=hibernate-search-orm-elasticsearch-quickstart"

このコマンドは、以下のエクステンションをインポートするMaven構造体を生成します:

Hibernate ORM with Panache,
PostgreSQL JDBCドライバー,
Hibernate Search + Elasticsearch,
RESTEasy Reactive と Jackson.

すでにQuarkusプロジェクトが設定されている場合はプロジェクトのベースディレクトリで以下のコマンドを実行すればプロジェクトに hibernate-search-orm-elasticsearch エクステンションを追加することができます:

コマンドラインインタフェース

quarkus extension add 'hibernate-search-orm-elasticsearch'

Maven

./mvnw quarkus:add-extension -Dextensions='hibernate-search-orm-elasticsearch'

Gradle

./gradlew addExtension --extensions='hibernate-search-orm-elasticsearch'

これにより、 pom.xml に以下が追加されます:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-search-orm-elasticsearch</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-hibernate-search-orm-elasticsearch")

ただのエンティティの作成

まず、 model サブパッケージに Hibernate ORM エンティティ Book と Author を作成しましょう。

package org.acme.hibernate.search.elasticsearch.model;

import java.util.List;
import java.util.Objects;

import jakarta.persistence.CascadeType;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.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;
    }
}

1	Hibernate ORM with Panacheを使用していますが、必須ではありません。
2	私たちは、これらの要素がJSON出力に存在するように前もってロードしています。実際のアプリケーションでは、おそらくDTOアプローチを使うべきでしょう。

package org.acme.hibernate.search.elasticsearch.model;

import java.util.Objects;

import jakarta.persistence.Entity;
import jakarta.persistence.ManyToOne;

import com.fasterxml.jackson.annotation.JsonIgnore;

import io.quarkus.hibernate.orm.panache.PanacheEntity;

@Entity
public class Book extends PanacheEntity {

    public String title;

    @ManyToOne
    @JsonIgnore (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;
    }
}

1	このプロパティを `@JsonIgnore` でマークしてJacksonでシリアル化する際の無限ループを避けます。

RESTサービスの初期化

まだRESTサービスの設定はすべて終わっていませんが、必要となる標準的なCRUD操作で初期化することができます。

org.acme.hibernate.search.elasticsearch.LibraryResource クラスを作成します:

package org.acme.hibernate.search.elasticsearch;

import java.util.List;
import java.util.Optional;

import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.MediaType;

import org.acme.hibernate.search.elasticsearch.model.Author;
import org.acme.hibernate.search.elasticsearch.model.Book;
import org.hibernate.search.mapper.orm.session.SearchSession;
import org.jboss.resteasy.reactive.RestForm;
import org.jboss.resteasy.reactive.RestQuery;

import io.quarkus.runtime.StartupEvent;

@Path("/library")
public class LibraryResource {

    @PUT
    @Path("book")
    @Transactional
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void addBook(@RestForm String title, @RestForm Long authorId) {
        Author author = Author.findById(authorId);
        if (author == null) {
            return;
        }

        Book book = new Book();
        book.title = title;
        book.author = author;
        book.persist();

        author.books.add(book);
        author.persist();
    }

    @DELETE
    @Path("book/{id}")
    @Transactional
    public void deleteBook(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(@RestForm String firstName, @RestForm 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(Long id, @RestForm String firstName, @RestForm 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(Long id) {
        Author author = Author.findById(id);
        if (author != null) {
            author.delete();
        }
    }
}

特別なことは何もありません。RESTサービスでのPanacheの処理と古き良きHibernateです。

実は、全文検索アプリケーションを動作させるために必要な要素はごくわずかです。

Hibernate Searchアノテーションの使用

エンティティに戻りましょう。

全文検索機能を有効にするには、いくつかのアノテーションを追加するだけで簡単です。

Book エンティティを再度編集して、この内容を入れてみましょう:

package org.acme.hibernate.search.elasticsearch.model;

import java.util.Objects;

import jakarta.persistence.Entity;
import jakarta.persistence.ManyToOne;

import org.hibernate.search.mapper.pojo.mapping.definition.annotation.FullTextField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;

import com.fasterxml.jackson.annotation.JsonIgnore;

import io.quarkus.hibernate.orm.panache.PanacheEntity;

@Entity
@Indexed (1)
public class Book extends PanacheEntity {

    @FullTextField(analyzer = "english") (2)
    public String title;

    @ManyToOne
    @JsonIgnore
    public Author author;

    // Preexisting equals()/hashCode() methods
}

1	まず、 `@Indexed` アノテーションを使って、 `Book` エンティティを全文検索インデックスの一部として登録してみましょう。
2	`@FullTextField` アノテーションは、全文検索用に特別に調整されたインデックスのフィールドを宣言します。特に、トークン（～単語）を分割して分析するためのアナライザーを定義する必要があります。 - これについては後で説明します。

Book がインデックス化されたことで、 Author にも同じことができるようになりました。

Author クラスを開き、以下の内容を記載します。

@Indexed 、 @FullTextField 、 @KeywordField のアノテーションを使用していますが、こちらもよく似ている機能です。

しかし、いくつかの違いや付加価値があります。それを見てみましょう。

package org.acme.hibernate.search.elasticsearch.model;

import java.util.List;
import java.util.Objects;

import jakarta.persistence.CascadeType;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.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
}

1	`@FullTextField` は `Book` と同様のものを使用しますが、アナライザーが異なることに気がつくでしょう - これについては後で説明します。
2	このように、同じプロパティに複数のフィールドを定義することができます。ここでは、固有の名前を持つ `@KeywordField` を定義しています。主な違いは、キーワードフィールドはトークン化されません（文字列は1つのトークンとして保持される）が、正規化（すなわちフィルタリング）することができるということです。これについては後で説明します。このフィールドは `Author` のソートに使用することを意図しているため、ソート可能であるとマークされています。
3	`@IndexedEmbedded` の目的は `Book` のフィールドを `Author` のインデックスに含めることです。この場合はデフォルトの設定を使用します。つまり、関連する `Book` エンティティのすべてのフィールドがインデックスに含まれます (つまり `title` フィールドも含まれます)。 `@IndexedEmbedded` の優れた点は双方向の関係により `Book` のいずれかが更新された場合も `Author` のインデックスを自動的に再作成できることです。 `@IndexedEmbedded` は、入れ子になったドキュメントもサポートしていますが（ `storage = NESTED` 属性を使用）ここでは必要ありません。また、すべてのフィールドを親インデックスに含める必要のない場合は、 `includePaths` 属性を使って含めるフィールドを指定することができます。

Programmatic mapping

If, for some reason, adding Hibernate Search annotations to entities is not possible, mapping can be applied programmatically instead. Programmatic mapping is configured through the ProgrammaticMappingConfigurationContext that is exposed via a mapping configurer (HibernateOrmSearchMappingConfigurer).

A mapping configurer (HibernateOrmSearchMappingConfigurer) allows much more than just programmatic mapping capabilities. It also allows configuring annotation mapping, bridges, and more.

Below is an example of a mapping configurer that applies programmatic mapping:

package org.acme.hibernate.search.elasticsearch.config;

import org.hibernate.search.mapper.orm.mapping.HibernateOrmMappingConfigurationContext;
import org.hibernate.search.mapper.orm.mapping.HibernateOrmSearchMappingConfigurer;
import org.hibernate.search.mapper.pojo.mapping.definition.programmatic.TypeMappingStep;

import io.quarkus.hibernate.search.orm.elasticsearch.SearchExtension;

@SearchExtension (1)
public class CustomMappingConfigurer implements HibernateOrmSearchMappingConfigurer {

	@Override
    public void configure(HibernateOrmMappingConfigurationContext context) {
        TypeMappingStep type = context.programmaticMapping()    (2)
            .type(SomeIndexedEntity.class);                     (3)
        type.indexed()                                          (4)
            .index(SomeIndexedEntity.INDEX_NAME);               (5)
        type.property("id").documentId();                       (6)
        type.property("text").fullTextField();                  (7)
    }
}

1	Annotate the configurer implementation with the `@SearchExtension` qualifier to tell Quarkus it should be used by Hibernate Search in the default persistence unit. The annotation can also target a specific persistence unit (`@SearchExtension(persistenceUnit = "nameOfYourPU")`).
2	Access the programmatic mapping context.
3	Create mapping step for the `SomeIndexedEntity` entity.
4	Define the `SomeIndexedEntity` entity as indexed.
5	Provide an index name to be used for the `SomeIndexedEntity` entity.
6	Define the document id property.
7	Define a full-text search field for the `text` property.

Alternatively, if for some reason you can’t or don’t want to annotate your mapping configurer with @SearchExtension, you can simply annotate it with @Dependent @Named("myMappingConfigurer") and then reference it from configuration properties:

quarkus.hibernate-search-orm.mapping.configurer=bean:myMappingConfigurer

アナライザーとノーマライザー

はじめに

アナライズは全文検索の大きな部分を占めています。インデックス作成や検索クエリ構築の際に、テキストがどのように処理されるかを定義します。

アナライザーの役割は、テキストをトークン（～単語）に分割し、フィルターをかけることです（例えば、すべて小文字にしたり、アクセントを削除したり）。

ノーマライザーは入力を1つのトークンとして保持する特殊なアナライザです。特に、キーワードのソートやインデックス作成に有効です。

多くのバンドルされたアナライザーがありますが、自分の目的に合わせて独自に開発することもできます。

Elasticsearchアナリシスフレームワークについては、 ElasticsearchドキュメントのText analysis セクションで詳しく説明しています。

使用するアナライザーの定義

エンティティにHibernate Searchアノテーションを追加する際に、使用するアナライザーとノーマライザーを定義しました。典型的には:

@FullTextField(analyzer = "english")

@FullTextField(analyzer = "name")

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

以下のものを使用しています:

人名用の name というアナライザー,
書籍のタイトル用の english というアナライザー,
ソートフィールド用の sort というノーマライザー

ですが、まだ設定していません。

それでは、Hibernate Searchを使ってどのように設定できるのか見てみましょう。

アナライザーのセットアップ

これは簡単な作業で、 ElasticsearchAnalysisConfigurer の実装を作成するだけです（そして、それを使用するようにQuarkusを設定します、詳細は後述します）。

要件を満たすために、次のような実装を作ってみましょう:

package org.acme.hibernate.search.elasticsearch.config;

import org.hibernate.search.backend.elasticsearch.analysis.ElasticsearchAnalysisConfigurationContext;
import org.hibernate.search.backend.elasticsearch.analysis.ElasticsearchAnalysisConfigurer;

import io.quarkus.hibernate.search.orm.elasticsearch.SearchExtension;

@SearchExtension (1)
public class AnalysisConfigurer implements ElasticsearchAnalysisConfigurer {

    @Override
    public void configure(ElasticsearchAnalysisConfigurationContext context) {
        context.analyzer("name").custom() (2)
                .tokenizer("standard")
                .tokenFilters("asciifolding", "lowercase");

        context.analyzer("english").custom() (3)
                .tokenizer("standard")
                .tokenFilters("asciifolding", "lowercase", "porter_stem");

        context.normalizer("sort").custom() (4)
                .tokenFilters("asciifolding", "lowercase");
    }
}

1	Configurerの実装に `@SearchExtension` アノテーションを付けて、QuarkusにすべてのElasticsearchインデックスに(デフォルトで)デフォルトの永続化ユニットを使用するように指示します。アノテーションは、特定の永続ユニット (`@SearchExtension(persistenceUnit = "nameOfYourPU")`)、バックエンド (`@SearchExtension(backend = "nameOfYourBackend")`)、インデックス (`@SearchExtension(index = "nameOfYourIndex")`)もターゲットにすることができます。
2	これは、スペースで単語を分離し、ASCII以外の文字をASCIIの対応する文字で置換し（したがって、アクセントを除去し）、すべてを小文字にするシンプルなアナライザーです。これは、例では著者名に使用されています。
3	これはもう少し積極的で、ステミングも含まれています。インデックス化された入力に `mysteries` が含まれていても、 `mystery` を検索して結果を得ることができます。人名に対しては確かに強引すぎますが、書籍のタイトルに対しては完璧です。
4	ここではソートに使われるノーマライザーを紹介します。最初のアナライザーと非常によく似ていますが、1つだけのトークンが欲しいので、単語をトークン化しないことを除けば同じです。

また、何らかの理由で @SearchExtension アノテーションを付けられない、あるいは付けたくない場合には、単純に @Dependent @Named("myAnalysisConfigurer") のアノテーションを付けて設定のプロパティから参照することも可能です:

quarkus.hibernate-search-orm.elasticsearch.analysis.configurer=bean:myAnalysisConfigurer

RESTサービスに全文検索機能を追加

既存の LibraryResource に、SearchSession をインジェクションするだけです:

    @Inject
    SearchSession searchSession; (1)

1	HibernateのSearchセッションを注入します。これは、フードの下の `EntityManager` に依存します。複数の永続化ユニットを持つアプリケーションは、CDI修飾子 `@io.quarkus.hibernate.orm.PersistenceUnit` を使って正しいものを選択することができます: CDI統合を参照。

そして、次のようなメソッドを追加します（いくつかの import もあります）:

    @Transactional (1)
    void onStart(@Observes StartupEvent ev) throws InterruptedException { (2)
        // only reindex if we imported some content
        if (Book.count() > 0) {
            searchSession.massIndexer()
                    .startAndWait();
        }
    }

    @GET
    @Path("author/search") (3)
    @Transactional
    public List<Author> searchAuthors(@RestQuery String pattern, (4)
            @RestQuery Optional<Integer> size) {
        return searchSession.search(Author.class) (5)
                .where(f ->
                    pattern == null || pattern.trim().isEmpty() ?
                        f.matchAll() : (6)
                        f.simpleQueryString()
                                .fields("firstName", "lastName", "books.title").matching(pattern) (7)
                )
                .sort(f -> f.field("lastName_sort").then().field("firstName_sort")) (8)
                .fetchHits(size.orElse(20)); (9)
    }

1	重要なポイント：これらのメソッドには、トランザクションコンテキストが必要です。
2	SQLスクリプトを使用してPostgreSQLデータベースにデータをインポートするために起動時にデータのインデックスを再作成する必要があります。Hibernate Searchのマスインデクサーを使用して大量のデータを効率的にインデクシングすることができます（パフォーマンスを向上させるために微調整できます）。Hibernate ORMの操作によるその後のすべての更新は自動的に全文インデックスに同期されます。マスインデクサーを使用するのはインデクシング構成を変更したりして（新しいフィールドの追加、アナライザーの構成の変更など）、新しい構成を既存のエンティティに適用したい場合のみです。
3	エンティティにアノテーションを追加するだけで、全文検索が可能になり、Hibernate Search DSLを使ってインデックスにクエリーを投げることができるようになります。
4	パラメーター名の繰り返しを避けるために `org.jboss.resteasy.annotations.jaxrs.QueryParam` アノテーションを使用します。
5	`Author` を検索していることを示しています。
6	述語を作成します。パターンが空の場合は `matchAll()` 述語を使用します。
7	有効なパターンがあれば、パターンにマッチする `firstName` 、 `lastName` 、 `books.title` フィールドに対する `simpleQueryString()` 述語を作成します。
8	結果のソート順を定義します。ここでは、姓でソートし、次に名でソートしています。ソートには作成した特定のフィールドを使用していることに注意してください。
9	`size` で指定した数の一致度が高いものをフェッチします。デフォルトでは `20` です。もちろんページングもサポートしています。

Hibernate Search DSLはElasticsearchの述語（match、range、nested、phrase、spatial…）の重要なサブセットをサポートしています。オートコンプリートを使ってDSLをご自由にお試しください。

When that’s not enough, you can always fall back to defining a predicate using JSON directly.

アプリケーションの設定

いつものように、Quarkusの設定ファイル（ application.properties ）ですべての設定を行うことができます。

以下の内容の src/main/resources/import.sql ファイルを作成してみましょう:

quarkus.ssl.native=false (1)

quarkus.datasource.db-kind=postgresql (2)

quarkus.hibernate-orm.sql-load-script=import.sql (3)

quarkus.hibernate-search-orm.elasticsearch.version=8 (4)
quarkus.hibernate-search-orm.indexing.plan.synchronization.strategy=sync (5)

%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/quarkus_test (6)
%prod.quarkus.datasource.username=quarkus_test
%prod.quarkus.datasource.password=quarkus_test
%prod.quarkus.hibernate-orm.database.generation=create
%prod.hibernate-search-orm.elasticsearch.hosts=localhost:9200 (6)

1	SSLは使用しないので、ネイティブ実行可能ファイルをよりコンパクトにするために無効にしています。
2	それでは、PostgreSQLのデータソースを作成してみましょう。
3	いくつかの初期データを読み込みます。
4	使用するElasticsearchのバージョンについて、Hibernate Searchに伝える必要があります。バージョンによってElasticsearchのマッピング構文に大きな違いがあるため、重要です。マッピングは起動時間を短縮するためにビルド時に作成されるため、Hibernate Searchはクラスタに接続してバージョンを自動検出することはできません。なお、OpenSearchの場合、バージョンの前に `opensearch:` を付ける必要があります。 OpenSearchの互換性を参照してください。
5	これは、エンティティが検索可能になるのを待ってから書き込みが完了したとみなすことを意味します。本番環境では、デフォルトの `write-sync` の方がパフォーマンスが高くなります。テスト時にはエンティティがすぐに検索可能になる必要があるため `sync` を使用することが特に重要です。
6	開発およびテストでは、我々は Dev Services に頼っています。つまり、QuarkusはPostgreSQLデータベースとElasticsearchクラスタを自動的に開始します。しかし、本番モードでは、PostgreSQLデータベースとElasticsearchクラスターを手動で起動したいと思うでしょう。そのため、Quarkusに、この接続情報を `prod` プロファイル（ `%prod.` プレフィックス）で提供するのです。

Dev Services に依存しているため、データベースと Elasticsearch スキーマは、tests と dev モードの各アプリケーション起動時に自動的にドロップされて再作成されます（ただし quarkus.hibernate-search-orm.schema-management.strategy が明示的に設定されていない限り）。

何らかの理由でDev Servicesを利用できない場合は以下のプロパティを設定することで、同様の動作をさせることができます:

%dev.quarkus.hibernate-orm.database.generation=drop-and-create
%test.quarkus.hibernate-orm.database.generation=drop-and-create
%dev.quarkus.hibernate-search-orm.schema-management.strategy=drop-and-create
%test.quarkus.hibernate-search-orm.schema-management.strategy=drop-and-create

quarkus.hibernate-search-orm.schema-management.strategy を参照してください。

Hibernate Searchエクステンションの設定の詳細については、設定リファレンスを参照してください。

開発サービス（コンフィグレーション・フリー・データベース）

Quarkusは、Dev Servicesという機能をサポートしており、設定なしでさまざまなコンテナを起動することができます。Elasticsearchの場合はこのサポートはデフォルトのElasticsearch接続にも及んでいます。つまり、 quarkus.hibernate-search-orm.elasticsearch.hosts を設定していない場合、テスト実行時や開発モード時にQuarkusは自動的にElasticsearchコンテナを起動し、接続を自動的に設定します。

アプリケーションの本番環境版を実行する場合、Elasticsearch接続は通常通り設定する必要があります。したがって、 application.properties に本番環境版のデータベース設定を含め、Dev Servicesを引き続き使用したい場合は、 %prod. プロファイルを使用してElasticsearch設定を定義することをお勧めします。

Dev Services for Elasticsearchは現時点では複数のクラスタを同時に起動することができず、デフォルトの永続化ユニットのデフォルトのバックエンドでのみ動作します:名前付き永続化ユニットや名前付きバックエンドはDev Services for Elasticsearchを利用することができません。

詳細については、 Dev Services for Elasticsearch ガイドをご覧ください。

フロントエンドの作成

それでは、 LibraryResource を操作するための簡単なWebページを追加してみましょう。Quarkusは、 META-INF/resources ディレクトリの下にある静的リソースを自動的に提供します。 src/main/resources/META-INF/resources ディレクトリで、既存の index.html ファイルを、この index.html ファイルの内容で上書きしてください。

自動インポートスクリプト

このデモの目的のために、初期データセットをインポートしてみましょう。

以下の内容の src/main/resources/import.sql ファイルを作成してみましょう:

INSERT INTO author(id, firstname, lastname) VALUES (1, 'John', 'Irving');
INSERT INTO author(id, firstname, lastname) VALUES (2, 'Paul', 'Auster');
ALTER SEQUENCE author_seq RESTART WITH 3;

INSERT INTO book(id, title, author_id) VALUES (1, 'The World According to Garp', 1);
INSERT INTO book(id, title, author_id) VALUES (2, 'The Hotel New Hampshire', 1);
INSERT INTO book(id, title, author_id) VALUES (3, 'The Cider House Rules', 1);
INSERT INTO book(id, title, author_id) VALUES (4, 'A Prayer for Owen Meany', 1);
INSERT INTO book(id, title, author_id) VALUES (5, 'Last Night in Twisted River', 1);
INSERT INTO book(id, title, author_id) VALUES (6, 'In One Person', 1);
INSERT INTO book(id, title, author_id) VALUES (7, 'Avenue of Mysteries', 1);
INSERT INTO book(id, title, author_id) VALUES (8, 'The New York Trilogy', 2);
INSERT INTO book(id, title, author_id) VALUES (9, 'Mr. Vertigo', 2);
INSERT INTO book(id, title, author_id) VALUES (10, 'The Brooklyn Follies', 2);
INSERT INTO book(id, title, author_id) VALUES (11, 'Invisible', 2);
INSERT INTO book(id, title, author_id) VALUES (12, 'Sunset Park', 2);
INSERT INTO book(id, title, author_id) VALUES (13, '4 3 2 1', 2);
ALTER SEQUENCE book_seq RESTART WITH 14;

アプリケーションで遊ぶ時間

これで、REST サービスと対話できるようになりました:

次のようにQuarkusアプリケーションを起動します:
コマンドラインインタフェース
```
quarkus dev
```
Maven
```
./mvnw quarkus:dev
```
Gradle
```
./gradlew --console=plain quarkusDev
```
ブラウザで http://localhost:8080/ を開きます
著者や書名の検索してください（いくつかのデータを入れておきました）
新しい著者や書籍を作成し、それらを検索することもできます

ご覧のように、すべての更新が自動的にElasticsearchクラスタに同期されます。

OpenSearch対応

Hibernate Searchは Elasticsearchと OpenSearchの両方に対応していますが、デフォルトではElasticsearchクラスタとの連携を前提としています。

To have Hibernate Search work with an OpenSearch cluster instead, prefix the configured version with opensearch:, as shown below.

quarkus.hibernate-search-orm.elasticsearch.version=opensearch:1.2

その他の設定オプションやAPIはElasticsearchの場合と全く同じです。

You can find more information about compatible distributions and versions of Elasticsearch in this section of Hibernate Search’s reference documentation.

複数の永続化ユニット

複数の永続化ユニットを設定

Hibernate ORM エクステンションでは、複数の永続化ユニットを設定することができ、それぞれが独自のデータソースと設定を持つことができます。

複数の永続化ユニットを宣言する場合は、それぞれの永続化ユニットに対して個別にHibernate Searchを設定することになります。

quarkus.hibernate-search-orm. 名前空間のルートにあるプロパティは、デフォルトの永続化ユニットを定義します。たとえば、次のスニペットでは、デフォルトのデータソースとデフォルトの永続化ユニットを定義し、その永続化ユニットのElasticsearchホストを es1.mycompany.com:9200 に設定しています。

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1

quarkus.hibernate-search-orm.elasticsearch.hosts=es1.mycompany.com:9200
quarkus.hibernate-search-orm.elasticsearch.version=8

マップベースのアプローチで名前付きの永続化ユニットを構成することも可能です:

quarkus.datasource."users".db-kind=h2 (1)
quarkus.datasource."users".jdbc.url=jdbc:h2:mem:users;DB_CLOSE_DELAY=-1

quarkus.datasource."inventory".db-kind=h2 (2)
quarkus.datasource."inventory".jdbc.url=jdbc:h2:mem:inventory;DB_CLOSE_DELAY=-1

quarkus.hibernate-orm."users".datasource=users (3)
quarkus.hibernate-orm."users".packages=org.acme.model.user

quarkus.hibernate-orm."inventory".datasource=inventory (4)
quarkus.hibernate-orm."inventory".packages=org.acme.model.inventory

quarkus.hibernate-search-orm."users".elasticsearch.hosts=es1.mycompany.com:9200 (5)
quarkus.hibernate-search-orm."users".elasticsearch.version=8

quarkus.hibernate-search-orm."inventory".elasticsearch.hosts=es2.mycompany.com:9200 (6)
quarkus.hibernate-search-orm."inventory".elasticsearch.version=8

1	`users` という名前のデータソースを定義します。
2	`inventory` という名前のデータソースを定義します。
3	`users` データソースを指す `users` という名前の永続化ユニットを定義します。
4	`inventory` データソースを指す `inventory` という名前の永続化ユニットを定義します。
5	`users` 永続化ユニットにHibernate Searchを設定し、その永続化ユニットのElasticsearchホストを `es1.mycompany.com:9200` に設定します。
6	`inventory` 永続化ユニットにHibernate Searchを設定し、その永続化ユニットのElasticsearchホストを `es2.mycompany.com:9200` に設定します。

モデルクラスの永続化ユニットへのアタッチメント

各永続化ユニットについて、Hibernate Searchは、その永続化ユニットにアタッチされているインデックス付きエンティティのみを考慮します。エンティティは、 Hibernate ORMエクステンションを設定することで、永続化ユニットにアタッチされます。

CDI統合

CDI を使用して、Hibernate Search のメインエントリーポイント SearchSession と SearchMapping をインジェクションすることができます:

@Inject
SearchSession searchSession;

これは、デフォルトの永続化ユニットの SearchSession をインジェクションします。

名前付き永続化ユニット(この例では users )の SearchSession をインジェクションするには、修飾子を追加するだけです:

@Inject
@PersistenceUnit("users") (1)
SearchSession searchSession;

1	これは `@io.quarkus.hibernate.orm.PersistenceUnit` アノテーションです。

全く同じメカニズムを使って、名前付き永続化ユニットの SearchMapping をインジェクションすることができます:

@Inject
@PersistenceUnit("users")
SearchMapping searchMapping;

ネイティブ実行可能ファイルの構築

以下のコマンドでネイティブの実行可能ファイルをビルドすることができます。

コマンドラインインタフェース

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.package.type=native

ネイティブ実行可能ファイルのコンパイルと同様に、この操作は大量のメモリーを消費します。

ネイティブ実行可能ファイルをビルドしている間は2つのコンテナーを停止して、ビルドが終わったら再度起動した方が安全かもしれません。

実行は ./target/hibernate-search-orm-elasticsearch-quickstart-1.0-SNAPSHOT-runner を実行するだけで簡単です。

その後、ブラウザで http://localhost:8080/ を開きアプリケーションを使用します。

起動がいつもより少し遅いのは、起動時に毎回データベーススキーマとElasticsearchマッピングを削除して再作成しているのが原因です。また、いくつかのデータを登録し、マスインデクサーを実行しています。

実際のアプリケーションでは、明らかに起動時に実行しないことです。

オフライン起動

デフォルトではHibernate Search は起動時に Elasticsearch クラスタにいくつかのリクエストを送信します。Hibernate Searchの起動時にElasticsearchクラスタが稼働していない場合は起動失敗の原因となります。

これに対処するためには起動時にリクエストを送信しないようにHibernate Searchを設定します:

起動時にElasticsearchのバージョンチェックを行わないようにするには、設定プロパティ quarkus.hibernate-search-orm.elasticsearch.version-check.enabled を false に設定します。
設定プロパティ quarkus.hibernate-search-orm.schema-management.strategyを none に設定すると起動時のスキーマ管理を無効にすることができます。

もちろん、この構成でも、Elasticsearchクラスタにアクセスできるようになるまでは、Hibernate Searchはインデックスを作成したり、検索クエリを実行したりすることはできません。

quarkus.hibernate-search-orm.schema-management.strategy を none に設定してスキーマの自動作成を無効にした場合、アプリケーションがエンティティの永続化/更新や検索リクエストの実行を開始する前に、手動でスキーマを作成する必要があります。

See this section of the reference documentation for more information.

アウトボックスポーリングによる調整

アウトボックスポーリングによる調整は、プレビューとみなされます。

プレビュー版 では、後方互換性やエコシステムでの存在は保証されていません。具体的な改善のためには、設定やAPI、あるいはストレージのフォーマットを変更する必要があるかもしれませんが、 安定化 に向けた計画は進行中です。ご意見・ご感想は、メーリングリストや GitHubのイシュートラッカーでお寄せください。

While it’s technically possible to use Hibernate Search and Elasticsearch in distributed applications, by default they suffer from a few limitations.

これらはHibernate Searchがデフォルトではスレッドやアプリケーションノード間の調整を行わないことによる制限です。

In order to get rid of these limitations, you can use the outbox-polling coordination strategy. This strategy creates an outbox table in the database to push entity change events to, and relies on a background processor to consume these events and perform indexing.

outbox-polling 調整ストラテジーを有効にするには、追加のエクステンションが必要です:

コマンドラインインタフェース

quarkus extension add 'hibernate-search-orm-coordination-outbox-polling'

Maven

./mvnw quarkus:add-extension -Dextensions='hibernate-search-orm-coordination-outbox-polling'

Gradle

./gradlew addExtension --extensions='hibernate-search-orm-coordination-outbox-polling'

エクステンションをインストールしたら、 quarkus.hibernate-search-orm.coordination.strategyを outbox-polling に設定し、明示的に outbox-polling ストラテジーを選択する必要があります。

最後に、Hibernate Searchによって追加されたHibernate ORMエンティティ（アウトボックスとエージェントを表す）が、データベース内に対応するテーブル/シーケンスを持っていることを確認する必要があります:

アプリケーションを始めたばかりで、 Hibernate ORMにデータベーススキーマを生成させるつもりであれば、心配ありません。Hibernate Searchが必要とするエンティティは、生成されたスキーマに含まれます。
Otherwise, you must manually alter your schema to add the necessary tables/sequences.

The database schema Hibernate Search will expect for outbox-polling coordination may be customized through the following configuration properties:

quarkus.hibernate-search-orm.coordination.entity.mapping.agent.catalog
quarkus.hibernate-search-orm.coordination.entity.mapping.agent.schema
quarkus.hibernate-search-orm.coordination.entity.mapping.agent.table
quarkus.hibernate-search-orm.coordination.entity.mapping.agent.uuid-gen-strategy
quarkus.hibernate-search-orm.coordination.entity.mapping.agent.uuid-type
quarkus.hibernate-search-orm.coordination.entity.mapping.outbox-event.catalog
quarkus.hibernate-search-orm.coordination.entity.mapping.outbox-event.schema
quarkus.hibernate-search-orm.coordination.entity.mapping.outbox-event.table
quarkus.hibernate-search-orm.coordination.entity.mapping.outbox-event.uuid-gen-strategy
quarkus.hibernate-search-orm.coordination.entity.mapping.outbox-event.uuid-type

上記の作業が完了したら、アウトボックスを使ったHibernate Searchを使用する準備が整いました。コードを変更せず、アプリケーションを起動するだけで大丈夫です。複数のアプリケーションが同じデータベースに接続されていることを自動的に検出し、それに応じてインデックスの更新が調整されます。

Hibernate Searchは、 outbox-polling 調整ストラテジーを使用してもしなくても、ほとんど同じ動作をします。アプリケーションコード（エンティティの永続化、検索など）を変更する必要はありません。

しかし重要な違いが1つあります。インデックスの更新は必然的に非同期で行われ、 いつかは 行われることが保証されますが、すぐには行われません。

This means in particular that the configuration property quarkus.hibernate-search-orm.indexing.plan.synchronization.strategy cannot be set when using the outbox-polling coordination strategy: Hibernate Search will always behave as if this property was set to write-sync (the default).

この動作は、Elasticsearchの Near real-time searchと一致しており、連携が無効な場合でもHibernate Searchを使用する場合は推奨されています。

For more information about coordination in Hibernate Search, see this section of the reference documentation.

連携に関連する設定オプションの詳細については、 outboxポーリングによる連携の設定を参照してください。

AWSのリクエストの署名

Amazonが管理するElasticsearchサービスを使用する必要がある場合、リクエストの署名を含む独自の認証方法を必要になります。

Hibernate SearchでAWSリクエストの署名を有効にするには、専用のエクステンションをプロジェクトに追加して設定します。

詳細は Hibernate Search ORM + Elasticsearch AWS エクステンションのドキュメントを参照してください。

参考資料

If you are interested in learning more about Hibernate Search 6, the Hibernate team publishes an extensive reference documentation.

FAQ

なぜElasticsearchだけなのか?

Hibernate SearchはLuceneバックエンドとElasticsearchバックエンドの両方をサポートしています。

Quarkusとマイクロサービスを構築するという文脈では、後者の方がより理にかなっていると考えました。そこで、私たちは後者に力を入れました。

今のところ、QuarkusでLuceneバックエンドをサポートする予定はありません。

Hibernate Search 設定リファレンス

主な構成

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

型

デフォルト

quarkus.hibernate-search-orm.enabled

Whether Hibernate Search is enabled during the build.

If Hibernate Search is disabled during the build, all processing related to Hibernate Search will be skipped, but it will not be possible to activate Hibernate Search at runtime: quarkus.hibernate-search-orm.active will default to false and setting it to true will lead to an error.

Environment variable: QUARKUS_HIBERNATE_SEARCH_ORM_ENABLED

boolean

true

quarkus.hibernate-search-orm.background-failure-handler

quarkus.hibernate-search-orm."persistence-unit-name".background-failure-handler

A bean reference to a component that should be notified of any failure occurring in a background process (mainly index operations).

The referenced bean must implement FailureHandler.

Instead of setting this configuration property, you can simply annotate your custom FailureHandler implementation with @SearchExtension and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically. If this configuration property is set, it takes precedence over any @SearchExtension annotation.

Environment variable: QUARKUS_HIBERNATE_SEARCH_ORM_BACKGROUND_FAILURE_HANDLER

string

quarkus.hibernate-search-orm.coordination.strategy

quarkus.hibernate-search-orm."persistence-unit-name".coordination.strategy

The strategy to use for coordinating between threads or even separate instances of the application, in particular in automatic indexing.

See coordination for more information.

Environment variable: QUARKUS_HIBERNATE_SEARCH_ORM_COORDINATION_STRATEGY

string

none

quarkus.hibernate-search-orm.mapping.configurer

quarkus.hibernate-search-orm."persistence-unit-name".mapping.configurer

One or more bean references to the component(s) used to configure Hibernate Search mapping.

The referenced beans must implement HibernateOrmSearchMappingConfigurer.

See Programmatic mapping for an example on how mapping configurers can be used to apply programmatic mappings.

Instead of setting this configuration property, you can simply annotate your custom HibernateOrmSearchMappingConfigurer implementations with @SearchExtension and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically. If this configuration property is set, it takes precedence over any @SearchExtension annotation.

Environment variable: QUARKUS_HIBERNATE_SEARCH_ORM_MAPPING_CONFIGURER

list of string

quarkus.hibernate-search-orm.active

quarkus.hibernate-search-orm."persistence-unit-name".active

Whether Hibernate Search should be active for this persistence unit at runtime.

If Hibernate Search is not active, it won’t index Hibernate ORM entities, and accessing the SearchMapping/SearchSession of the relevant persistence unit for search or other operation will not be possible.

Note that if Hibernate Search is disabled (i.e. quarkus.hibernate-search-orm.enabled is set to false), it won’t be active for any persistence unit, and setting this property to true will fail.

Environment variable: QUARKUS_HIBERNATE_SEARCH_ORM_ACTIVE

boolean

'true' if Hibernate Search is enabled; 'false' otherwise

quarkus.hibernate-search-orm.schema-management.strategy

quarkus.hibernate-search-orm."persistence-unit-name".schema-management.strategy

The schema management strategy, controlling how indexes and their schema are created, updated, validated or dropped on startup and shutdown.

Available values:

Strategy

Definition

none

Do nothing: assume that indexes already exist and that their schema matches Hibernate Search’s expectations.

validate

Validate that indexes exist and that their schema matches Hibernate Search’s expectations.

If it does not, throw an exception, but make no attempt to fix the problem.

create