将 Hibernate Search 与 Hibernate ORM 及 Elasticsearch／OpenSearch 配合使用

你已有一个基于 Hibernate ORM 的应用，想向用户提供功能完整的全文搜索？本指南将介绍如何使用 Hibernate Search，快速把实体同步到 Elasticsearch 或 OpenSearch 集群，并通过 Hibernate Search API 查询集群。

如果需要索引的实体并非 Hibernate ORM 实体，请阅读专门的独立模式指南。

前提条件

完成本指南需要：

• 大约20分钟。
• 一个 IDE。
• 已安装 JDK 17+，并正确配置 JAVA_HOME。
• Apache Maven 3.9.16。
• 可用的容器运行时：Docker 或 Podman。
• 可选：如果希望使用 Quarkus CLI，请先安装。
• 可选：如果希望构建原生可执行文件，请安装 Mandrel 或 GraalVM 并正确配置；使用原生容器构建时也可使用 Docker。

架构

本指南的应用用于管理一个简单的图书馆，包括作者及其图书。实体存储在 PostgreSQL 数据库中，并在 Elasticsearch 集群中建立索引。

完整示例

Quarkus 文档作者建议跟随后续步骤逐步创建应用，也可以直接查看完整示例。

克隆 Git 仓库：git clone https://github.com/quarkusio/quarkus-quickstarts.git（仓库地址），或下载归档文件。完整示例位于 hibernate-search-orm-elasticsearch-quickstart 目录。

完整示例还包含测试及测试基础设施等额外内容。

创建 Maven 项目

首先创建新项目。

CLI：

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

若要创建 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。安装及使用方法参见 Quarkus CLI 指南。

Maven：

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

若要创建 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

Windows 用户需要注意：

• 使用 cmd 时，不要使用反斜杠 \ 续行，应将整个命令写在同一行。
• 使用 PowerShell 时，用双引号包围 -D 参数，例如 "-DprojectArtifactId=hibernate-search-orm-elasticsearch-quickstart"。

此命令生成 Maven 项目结构，并引入 Hibernate ORM with Panache、PostgreSQL JDBC 驱动、Hibernate Search + Elasticsearch，以及 Quarkus REST（以前称为 RESTEasy Reactive）和 Jackson 扩展。

如果已经配置好 Quarkus 项目，可在项目根目录执行以下命令添加 hibernate-search-orm-elasticsearch 扩展。

CLI：

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 添加以下内容：

<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 服务中常见的 Hibernate ORM with Panache 操作。接下来只需添加很少的内容，就能让全文搜索应用工作。

使用 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 在索引中声明一个专门用于全文搜索的字段。需要定义分析器，将文本拆分为词元（近似于单词）并分析；后文会详细说明。

图书已建立索引，接着处理作者。打开 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. 与 Book 类似，这里使用 @FullTextField，但分析器不同；后文会说明。
2. 同一属性可以定义多个索引字段。这里定义了具有特定名称的 @KeywordField。关键词字段不会分词，整个字符串保留为单个词元，但可以进行规范化，即过滤处理；后文会说明。由于要按作者排序，此字段标记为可排序。
3. @IndexedEmbedded 将 Book 的字段纳入 Author 索引。这里采用默认配置：关联 Book 实体的所有字段都纳入索引，即 title 字段。借助双向关联，其中一本 Book 更新时，Hibernate Search 能自动重新索引其 Author。

@IndexedEmbedded 也支持嵌套文档，使用 structure = NESTED 属性即可，但本例不需要。如果不希望嵌入所有字段，可使用 includePaths／excludePaths 指定嵌入父索引的字段。

分析器与规范化器

简介

文本分析是全文搜索的重要部分，决定在索引文本或构建搜索查询时如何处理文本。

分析器把文本拆分成词元，再执行过滤，例如转为小写、去除重音符号。规范化器是一类特殊的分析器，始终把输入保留为一个词元，尤其适合排序和关键词索引。系统自带许多分析器，也可以按特定需求开发自己的分析器。

更多信息参见 Elasticsearch 文档的文本分析部分。

定义所用的分析器

添加 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. 在配置器实现上添加 @SearchExtension 限定符，告诉 Quarkus 默认将其用于默认持久化单元的所有 Elasticsearch 索引。此注解也可指定持久化单元 @SearchExtension(persistenceUnit = "nameOfYourPU")、后端 @SearchExtension(backend = "nameOfYourBackend")、索引 @SearchExtension(index = "nameOfYourIndex")，或其组合：@SearchExtension(persistenceUnit = "nameOfYourPU", backend = "nameOfYourBackend", index = "nameOfYourIndex")。
2. 这是一个简单分析器：按空格分隔单词，把非 ASCII 字符替换为对应 ASCII 字符以去除重音，并全部转为小写。本例将它用于作者姓名。
3. 此分析器处理得更积极，加入了词干提取：即使索引输入是 mysteries，搜索 mystery 也能命中。这种处理对人名过于激进，但适合书名。
4. 排序规范化器与第一个分析器相似，但不进行分词，因为需要保留且只保留一个词元。

如果不能或不想用 @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，即可用 Hibernate Search DSL 查询索引：

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

1. 此方法需要事务上下文。
2. 使用 org.jboss.resteasy.reactive.RestQuery 注解，避免重复写参数名。
3. 指定搜索 Author。
4. 创建谓词：模式为空时使用 matchAll()。
5. 模式有效时，在 firstName、lastName 和 books.title 字段上创建匹配该模式的 simpleQueryString() 谓词。
6. 定义结果排序：先按姓氏，再按名字；使用此前专门创建的排序字段。
7. 获取前 size 条命中结果，默认 20 条；也支持分页。

Hibernate Search DSL 支持 Elasticsearch 谓词的一个很大子集，包括 match、range、nested、phrase、spatial 等。可以借助自动补全探索 DSL。如果仍不够用，也可以直接使用 JSON 定义谓词。

自动初始化数据

为演示导入一组初始数据。创建 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;

这些数据直接写入数据库，Hibernate Search 无法感知，因此不会被索引。之后通过 Hibernate ORM 操作产生的更新则会自动同步到全文索引。

在已有的 LibraryResource 中添加以下内容及所需的 import，为初始数据建立索引。

如果没有向数据库手工导入数据，就不需要此步骤。此时仅在更改索引配置，例如添加字段或修改分析器配置，并希望将新配置应用于已有数据时，才需要使用批量索引器。

    @Inject
    SearchMapping searchMapping; (1)

    void onStart(@Observes StartupEvent ev) throws InterruptedException { (2)
        // only reindex if we imported some content
        if (Book.count() > 0) {
            searchMapping.scope(Object.class) (3)
                    .massIndexer() (4)
                    .startAndWait(); (5)
        }
    }

1. 注入底层依赖 EntityManagerFactory 的 Hibernate Search SearchMapping。多持久化单元应用可使用 CDI 限定符 @io.quarkus.hibernate.orm.PersistenceUnit 选择正确的单元，参见 CDI 集成。
2. 添加应用启动时执行的方法。
3. 创建搜索范围，包含所有继承 Object 的已索引实体类型，即本例全部已索引实体 Author 和 Book。
4. 创建 Hibernate Search 批量索引器，高效索引大量数据；可以进一步调优以改善性能。
5. 启动批量索引器并等待完成。

配置应用

所有配置都可放入 Quarkus 配置文件 application.properties。编辑 src/main/resources/application.properties：

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

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

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

%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/quarkus_test
%prod.quarkus.datasource.username=quarkus_test
%prod.quarkus.datasource.password=quarkus_test
%prod.quarkus.hibernate-orm.schema-management.strategy=create
%prod.quarkus.hibernate-search-orm.elasticsearch.hosts=localhost:9200 (5)

1. 创建 PostgreSQL 数据源。
2. 启动时加载初始数据，参见自动初始化数据。
3. 指定要使用的 Elasticsearch 版本。不同版本的映射语法存在明显差异，因此此配置很重要。为缩短启动时间，映射在构建时生成，Hibernate Search 不能连接集群来自动检测版本。使用 OpenSearch 时，版本须带 opensearch: 前缀，参见 OpenSearch 兼容性。
4. 写入完成之前，等待实体可被搜索。生产环境使用默认的 write-sync 性能更好；测试需要实体立即可搜索，因此 sync 尤其重要。
5. 开发和测试依靠 Dev Services 自动启动 PostgreSQL 数据库及 Elasticsearch 集群。生产模式需要手工启动它们，因此在 prod 配置集（%prod. 前缀）中提供连接信息。

由于使用 Dev Services，测试和开发模式下每次启动应用都会自动删除并重建数据库及 Elasticsearch 模式，除非显式设置 quarkus.hibernate-search-orm.schema-management.strategy。如果无法使用 Dev Services，可用以下配置取得类似行为：

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

另请参见 quarkus.hibernate-search-orm.schema-management.strategy。Hibernate Search ORM 扩展的更多配置见配置参考。

创建前端

添加一个简单网页与 LibraryResource 交互。Quarkus 自动提供 META-INF/resources 下的静态资源。在 src/main/resources/META-INF/resources 目录中，用该 index.html 文件的内容覆盖现有 index.html。

体验应用

现在可以与 REST 服务交互。

首先启动 Quarkus 应用。

CLI：

quarkus dev

Maven：

./mvnw quarkus:dev

Gradle：

./gradlew --console=plain quarkusDev

然后在浏览器中打开 http://localhost:8080/，搜索作者或书名；示例已经初始化了一些数据。也可以创建新作者和图书，再搜索它们。所有更新都会自动同步到 Elasticsearch 集群。

构建原生可执行文件

使用常规命令构建原生可执行文件。

CLI：

quarkus build --native

Maven：

./mvnw install -Dnative

Gradle：

./gradlew build -Dquarkus.native.enabled=true

原生可执行文件编译通常会消耗大量内存。构建期间先停止两个容器，构建后再启动，可能更稳妥。

运行 ./target/hibernate-search-orm-elasticsearch-quickstart-1.0.0-SNAPSHOT-runner 即可启动原生可执行文件，然后在浏览器中打开 http://localhost:8080/ 使用应用。

此示例启动比平时稍慢，主要因为每次启动都会删除并重建数据库模式及 Elasticsearch 映射，同时导入数据并运行批量索引器。实际应用显然不会在每次启动时执行这些操作。

Dev Services：免配置数据存储

Quarkus 的 Dev Services 功能可以免配置启动各种容器。

对于 Elasticsearch，此功能适用于默认连接。没有配置 quarkus.hibernate-search-orm.elasticsearch.hosts 时，Quarkus 会在测试或开发模式中自动启动 Elasticsearch 容器并配置连接。

生产版本仍须正常配置 Elasticsearch 连接。因此，如果既希望在 application.properties 中保留生产配置，又继续使用 Dev Services，Quarkus 文档作者建议使用 %prod. 配置集定义 Elasticsearch 设置。

Dev Services for Elasticsearch 目前不能同时启动多个集群，因此只适用于默认持久化单元的默认后端；命名持久化单元或命名后端无法使用该功能。

更多信息参见 Dev Services for Elasticsearch 指南。

编程式映射

如果无法向实体添加 Hibernate Search 注解，也可通过程序应用映射。映射配置器 HibernateOrmSearchMappingConfigurer 暴露的 ProgrammaticMappingConfigurationContext 用于配置编程式映射。

映射配置器不仅支持编程式映射，还可以配置注解映射、桥接器等。

示例如下：

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. 用 @SearchExtension 限定符标记配置器实现，让默认持久化单元中的 Hibernate Search 使用它。也可通过 @SearchExtension(persistenceUnit = "nameOfYourPU") 指定持久化单元。
2. 获取编程式映射上下文。
3. 为 SomeIndexedEntity 实体创建映射步骤。
4. 将 SomeIndexedEntity 定义为已索引实体。
5. 指定该实体使用的索引名称。
6. 定义文档 ID 属性。
7. 为 text 属性定义全文搜索字段。

如果不能或不想使用 @SearchExtension，可改用 @Dependent @Named("myMappingConfigurer")，再从配置属性中引用：

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

OpenSearch 兼容性

Hibernate Search 同时兼容 Elasticsearch 和 OpenSearch，但默认假定连接的是 Elasticsearch 集群。

要使用 OpenSearch，为配置的版本添加 opensearch: 前缀：

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

其他配置选项及 API 与 Elasticsearch 完全相同。有关兼容的 Elasticsearch 发行版及版本，参见 Hibernate Search 参考文档对应章节。

多个持久化单元

配置多个持久化单元

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=9

也可通过映射式配置定义命名持久化单元：

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=9

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

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 的 Hibernate Search with Hibernate ORM 扩展会自动向 Hibernate Search 注入带 @SearchExtension 注解的组件。

在组件类型支持的情况下，注解可指定持久化单元 @SearchExtension(persistenceUnit = "nameOfYourPU")、后端 @SearchExtension(backend = "nameOfYourBackend")、索引 @SearchExtension(index = "nameOfYourIndex")，或其组合：@SearchExtension(persistenceUnit = "nameOfYourPU", backend = "nameOfYourBackend", index = "nameOfYourIndex")。

此功能支持以下组件：

激活或停用 Hibernate Search

如果某个持久化单元在构建时已配置 Hibernate Search 索引，Hibernate Search 默认在该单元中处于激活状态，并随应用启动。

运行时将 quarkus.hibernate-search-orm-elasticsearch[.optional name].active 设为 false，可停用给定持久化单元中的 Hibernate Search。其行为类似 Hibernate ORM 扩展对应功能，但作用于 Hibernate Search bean。

离线启动

默认情况下，Hibernate Search 启动时会向 Elasticsearch 集群发送少量请求。如果集群此时尚未运行，应用可能启动失败。

可通过以下配置禁止启动时发送请求：

• 将 quarkus.hibernate-search-orm.elasticsearch.version-check.enabled 设为 false，停用启动时的 Elasticsearch 版本检查。
• 将 quarkus.hibernate-search-orm.schema-management.strategy 设为 none，停用启动时的模式管理。

即便如此，在 Elasticsearch 集群可访问之前，Hibernate Search 仍无法建立索引或执行搜索查询。

将 quarkus.hibernate-search-orm.schema-management.strategy 设为 none 以停用自动模式创建后，必须在应用开始持久化／更新实体及执行搜索之前，手工创建模式。参见参考文档对应章节。

通过 outbox 轮询协调

outbox 轮询协调功能处于预览阶段，不保证向后兼容，也不保证会持续保留在生态系统中。某些改进可能需要更改配置、API，甚至存储格式；团队正在推进稳定化。可通过邮件列表或 GitHub issue 跟踪器反馈意见。

技术上可以在分布式应用中使用 Hibernate Search 和 Elasticsearch，但默认存在一些限制，原因是 Hibernate Search 默认不在线程或应用节点之间执行协调。

要消除这些限制，可使用 outbox-polling 协调策略。此策略在数据库中创建 outbox 表，写入实体变更事件，再由后台处理器消费事件并建立索引。

启用该策略需要额外扩展。

CLI：

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

Maven：

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

Gradle：

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

安装扩展后，将 quarkus.hibernate-search-orm.coordination.strategy 设为 outbox-polling，显式选择策略。

还须确保 Hibernate Search 添加的 Hibernate ORM 实体（表示 outbox 及 agent）在数据库中具有对应表和序列：

• 如果应用刚开始开发，计划让 Hibernate ORM 生成数据库模式，生成的模式会包含 Hibernate Search 所需实体。
• 否则须手工修改模式，添加必要的表和序列。

可以通过以下属性自定义 outbox-polling 协调所需的数据库模式：

• 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

完成这些设置后，无须修改代码，直接启动应用。应用会自动检测是否有多个应用连接同一数据库，并据此协调索引更新。

outbox-polling 下的 Hibernate Search 大体保持原有行为，持久化实体、搜索等应用代码通常无须修改。主要差别是索引更新必然异步：保证最终发生，但不保证立即发生。因此不能设置 quarkus.hibernate-search-orm.indexing.plan.synchronization.strategy；Hibernate Search 始终表现为使用默认的 write-sync。此行为与 Elasticsearch 的近实时搜索一致，也是即使未启用协调时的推荐使用方式。

协调机制的详情参见参考文档对应章节；相关配置见outbox 轮询协调配置。

AWS 请求签名

Amazon 托管的 Elasticsearch 服务要求一种涉及请求签名的专有认证方式。可向项目添加专门扩展并配置，以在 Hibernate Search 中启用 AWS 请求签名。

更多信息参见 Hibernate Search ORM + Elasticsearch AWS 扩展文档。

管理端点

Hibernate Search 管理端点处于预览阶段，不保证向后兼容，也不保证会持续保留在生态系统中。某些改进可能需要更改配置、API，甚至存储格式；团队正在推进稳定化。可通过邮件列表或 GitHub issue 跟踪器反馈意见。

Hibernate Search 扩展通过管理接口提供用于重新索引数据的 HTTP 端点。默认不可用，可通过以下属性启用：

quarkus.management.enabled=true (1)
quarkus.hibernate-search-orm.management.enabled=true (2)

1. 启用管理接口。
2. 启用 Hibernate Search 专用管理端点。

启用后，可通过 /q/hibernate-search/reindex 重新索引数据。/q 是默认管理根路径，/hibernate-search 是默认 Hibernate Search 管理根路径，后者可配置：

quarkus.hibernate-search-orm.management.root-path=custom-root-path (1)

1. 使用自定义 custom-root-path。若采用默认管理根路径，重新索引路径变为 /q/custom-root-path/reindex。

此端点只接受内容类型为 application/json 的 POST 请求。请求体为空时，会重新索引所有已索引实体。若只需重新索引部分实体，或需自定义底层批量索引器配置，可在请求体中传入：

{
  "filter": {
    "types": ["EntityName1", "EntityName2", "EntityName3", ...], (1)
  },
  "massIndexer":{
    "typesToIndexInParallel": 1, (2)
  }
}

1. 需要重新索引的实体名称数组；未指定或为空时，重新索引所有实体类型。
2. 并行索引的实体类型数。

所有可用过滤条件及批量索引器配置如下：

{
  "filter": { (1)
    "types": ["EntityName1", "EntityName2", "EntityName3", ...], (2)
    "tenants": ["tenant1", "tenant2", ...] (3)
  },
  "massIndexer":{ (4)
    "typesToIndexInParallel": 1, (5)
    "threadsToLoadObjects": 6,  (6)
    "batchSizeToLoadObjects": 10, (7)
    "cacheMode": "IGNORE", (8)
    "mergeSegmentsOnFinish": false, (9)
    "mergeSegmentsAfterPurge": true, (10)
    "dropAndCreateSchemaOnStart": false, (11)
    "purgeAllOnStart": true, (12)
    "idFetchSize": 100, (13)
    "transactionTimeout": 100000, (14)
  }
}

1. 过滤对象，用于限定重新索引范围。
2. 实体名称数组；未指定或为空时，重新索引所有实体类型。
3. 多租户场景的租户 ID 数组；未指定或为空时，重新索引所有租户。
4. 批量索引器配置对象。
5. 并行索引的实体类型数。
6. 加载根实体所用的线程数。
7. 加载根实体的批大小。
8. 数据加载任务与缓存交互的模式。
9. 索引完成后是否将每个索引合并为一个分段。
10. 初始清空索引之后、开始索引之前，是否将每个索引合并为一个分段。
11. 索引前是否删除并重建已有索引及其模式。
12. 索引前是否从索引中删除所有实体。
13. 加载待索引对象的主键时使用的提取大小。
14. 加载待重新索引的 ID 和实体时，事务的超时。JSON 中的所有属性均为可选，只需使用需要的属性。

批量索引器配置详情参见 Hibernate Search 参考文档对应章节。

提交重新索引请求会触发后台索引，进度显示在应用日志中。测试时可能需要知道何时完成；在 URL 中添加 wait_for=finished 查询参数，管理端点就会返回分块响应，分别报告索引开始和完成。

多个持久化单元场景可通过 persistence_unit 查询参数指定要重新索引的单元：/q/hibernate-search/reindex?persistence_unit=non-default-persistence-unit。

延伸阅读

Hibernate 团队发布了详尽的 Hibernate Search 参考文档，并维护列出其他相关资源的页面。

常见问题

为什么只支持 Elasticsearch？

Hibernate Search 同时支持 Lucene 后端和 Elasticsearch 后端。Quarkus 团队认为，在 Quarkus 中构建可扩展应用时，后者更合适，因此将精力集中在后者。

团队目前没有在 Quarkus 中支持 Lucene 后端的计划，不过 Quarkiverse 中有一个 issue 跟踪相关实现：quarkiverse/quarkus-hibernate-search-extras#179。

Hibernate Search with Hibernate ORM 配置参考

主要配置

原文以锁定标记表示构建时固定的属性，其他属性可在运行时覆盖。下表保留配置项及其全部命名变体、环境变量、类型和默认值；具体构建时标记请参阅官方配置表。

模式管理策略

索引同步策略

下表说明应用线程恢复时的保证。保证项依据原文链接的 Hibernate Search 官方参考表以文字列出。

Elasticsearch／OpenSearch 后端配置

按索引覆盖配置

管理接口

Duration 格式

时间长度使用标准 java.time.Duration 格式，参见 Duration#parse() Java API 文档。也支持以数字开头的简写：

• 只有数字时表示秒。
• 数字后跟 ms 时表示毫秒。
• 其他情况先转换为 java.time.Duration 格式再解析：数字后跟 h、m 或 s 时加 PT 前缀，后跟 d 时加 P 前缀。

bean 引用

通过配置属性引用 bean 是可选方式，原文作者并不推荐；给 bean 添加 @SearchExtension 可达到相同效果，参见自定义组件。

如果确实希望在配置属性中用字符串引用 bean，该字符串会被解析，常用格式包括：

• bean: 后跟 @Named CDI bean 的名称，例如 bean:myBean。
• class: 后跟类的全限定名称；若该类是 CDI bean，通过 CDI 实例化，否则调用公开无参构造器。例如 class:com.mycompany.MyClass。
• 引用内置实现的字符串。可用值见各属性文档，例如 quarkus.hibernate-search-orm.indexing.plan.synchronization.strategy 的 async／read-sync／write-sync／sync。

也接受其他格式，但只对高级用例有用，参见 Hibernate Search 参考文档对应章节。

outbox 轮询协调配置

以下配置项需要额外扩展，参见通过 outbox 轮询协调。

原文以锁定标记表示构建时固定的属性，其他属性可在运行时覆盖；具体标记请参阅官方配置表。

持久化单元配置

outbox-polling 协调实体映射

按租户覆盖配置

Duration 格式

时间长度使用标准 java.time.Duration 格式，参见 Duration#parse() Java API 文档。也支持以数字开头的简写：

• 只有数字时表示秒。
• 数字后跟 ms 时表示毫秒。
• 其他情况先转换为 java.time.Duration 格式再解析：数字后跟 h、m 或 s 时加 PT 前缀，后跟 d 时加 P 前缀。

来源、许可与修改说明

原文：Use Hibernate Search with Hibernate ORM and Elasticsearch/OpenSearch。原作者：Quarkus 项目及文档贡献者。中文译文：未完纪。依据2026年10月3日读取的 Latest 版本页面翻译；示例使用 Quarkus 3.40.1、Elasticsearch 9 和 OpenSearch 3.5。

原文网站页脚及官方网站仓库说明将网站内容按 Creative Commons Attribution 3.0 Unported（CC BY 3.0）提供。本译文按该许可提供，保留来源署名、许可链接及变更说明；不表示 Quarkus 项目认可或背书本译文。原文另说明项目依赖采用 Apache Software License 2.0 或兼容许可；该说明与本网站内容的 CC BY 3.0 许可分别适用。

本版将正文、操作说明及完整配置参考译为中文，保留全部代码展示和代码中的编号标注；表格重新排版，链接改为绝对地址，部分链接采用官方读取结果中的页面地址。索引同步保证表依据原文链接的 Hibernate Search 官方参考表转为文字；配置表的构建时锁定标记以原网页为准。文中的建议和技术取舍归属于原文作者，示例输出和效果说明属于原文描述。