Hibernate Search 教程

昌琪

2023-12-01

Hibernate Search 教程

本文我们讨论Hibernate Search 基础知识、配置及查询搜索功能。

如果我们已经在ORM中使用Hibernate和JPA，那么离Hibernate Search只有一步之遥。Hibernate Search集成了Apache Lucene，一个高性能、可扩展的全文检索引擎。其结合了Lucene的强大功能和Hibernate和JPA的简单性，因此仅需在领域类上增加一些注解，数据库与索引的同步工作会自动完成。

Hibernate Search 也提供了Elasticsearch的集成，本文聚焦Lucene的实现。无论那种方式实现全文检索，使用我们熟悉的工具总是不错的选型。

1. 配置

1.1. 依赖

首先增加一些必要的依赖：

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-search-orm</artifactId>
    <version>5.8.2.Final</version>
</dependency>

为了示例简单，我们使用H2内存数据库：

<dependency>
    <groupId>com.h2database</groupId> 
    <artifactId>h2</artifactId>
    <version>1.4.196</version>
</dependency>

1.2. 配置

关键配置是Lucene索引存储位置，需要通过hibernate.search.default.directory_provider属性进行设置。

我们将选择filesystem，这是最直接的选择。官方文件中列出了更多的选项。对于集群应用程序来说，filesystemi-master/filesystemi-slave和infinispan是值得注意的，其中索引必须在节点之间同步。示例配置如下：

hibernate.search.default.directory_provider = filesystem
hibernate.search.default.indexBase = /data/index/default

1.3. 搜索模型类

完成配置后，需要指定模型类。在JPA注解@Entity 和 @Table的基础上增加@Indexed 注解，其告诉Hibernate Search 该实体需要被索引。然后再定义需要被索引的属性，增加@Field注解：

@Entity
@Indexed
@Table(name = "product")
public class Product {
 
    @Id
    private int id;
 
    @Field(termVector = TermVector.YES)
    private String productName;
 
    @Field(termVector = TermVector.YES)
    private String description;
 
    @Field
    private int memory;
 
    // getters, setters, and constructors
}

1.4. 生成Lucene索引

开始执行查询之前，需触发Lucene生成反向索引：

FullTextEntityManager fullTextEntityManager 
  = Search.getFullTextEntityManager(entityManager);
fullTextEntityManager.createIndexer().startAndWait();

初始化完成之后，当通过EntityManager创建、修改或删除实体时，Hibernate Search 会负责索引实时更新。
需要注意的是：必须确保实体被完全提交至数据库才能让Lucene生成索引，因此测试时需要使用@Commit注解。

2. 构建并执行查询

完成上面的配置之后，下面准备创建查询，先介绍构建查询流程。

2.1. 构建查询流程

主要包括四个步骤：

从FullTextEntityManager获取QueryBuilder

FullTextEntityManager fullTextEntityManager 
  = Search.getFullTextEntityManager(entityManager);
 
QueryBuilder queryBuilder = fullTextEntityManager.getSearchFactory() 
  .buildQueryBuilder()
  .forEntity(Product.class)
  .get();

通过 Hibernate query DSL创建Lucene查询：

org.apache.lucene.search.Query query = queryBuilder
  .keyword()
  .onField("productName")
  .matching("iphone")
  .createQuery();

包装Lucene 查询至 Hibernate查询：

org.hibernate.search.jpa.FullTextQuery jpaQuery
  = fullTextEntityManager.createFullTextQuery(query, Product.class);

执行查询

List<Product> results = jpaQuery.getResultList();

默认情况下Lucene按照相关性进行排序。步骤1、3、4对所有查询类型都一样，后面我们聚集步骤2实现不同的查询。

2.2. 关键词查询

即搜索特定关键词，代码如下：

Query keywordQuery = queryBuilder
  .keyword()
  .onField("productName")
  .matching("iphone")
  .createQuery();

keyword()指定搜索特定词，onField()告诉Lucene在哪里搜索，matching匹配需要搜索的关键词。

2.3. 近似查询

近似查询与关键词查询类似，只是可以定义一个“模糊”的限制，在这个限制内Lucene将接受两个术语为匹配结果。

通过ditdistanceupto()，可以定义术语之间的偏离程度。它可以设置为0、1和2，默认值为2(注意:这个限制来自Lucene的实现)。
通过withPrefixLength()，定义前缀的长度，这个长度是由模糊性所忽略的:

Query fuzzyQuery = queryBuilder
  .keyword()
  .fuzzy()
  .withEditDistanceUpTo(2)
  .withPrefixLength(0)
  .onField("productName")
  .matching("iPhaen")
  .createQuery();

2.4. 通配符查询

Hibernate Search也支持通配符查询,?号表示单个字符，*号表示任意字符:

Query wildcardQuery = queryBuilder
  .keyword()
  .wildcard()
  .onField("productName")
  .matching("Z*")
  .createQuery();

2.5. 短语搜索

如果想搜索多个词，可以使用短语搜索。使用phrase() 和 withSlop()方法，可以实现精确查询或近似句子。slop因子定义句子中允许其他词数量：

Query phraseQuery = queryBuilder
  .phrase()
  .withSlop(1)
  .onField("description")
  .sentence("with wireless charging")
  .createQuery();

2.5. 简单查询字符串搜索

前面的查询方式都需要指定查询类型。使用简单查询字符串可以实现更强大的搜索功能，即实现运行时查询能力。其支持的查询类型如下：

布尔类型（and 使用 +, or 使用 | , not 使用-）
前缀查询（前缀*）
短语查询（“一些短语”）
优先级(使用括号)
近似查询(近似词语~2)
短语查询的近邻运算符(“某些短语”~3)

下面示例综合了近似查询、词组查询以及布尔查询：

Query simpleQueryStringQuery = queryBuilder
  .simpleQueryString()
  .onFields("productName", "description")
  .matching("Aple~2 + \"iPhone X\" + (256 | 128)")
  .createQuery();

2.7. 范围查询

范围查询在一定范围内搜索值，可以应用于数值、日期、时间以及字符串：

Query rangeQuery = queryBuilder
  .range()
  .onField("memory")
  .from(64).to(256)
  .createQuery();

2.8. 同类词查询

最后一个查询类型是同类词查询（More Like This）。提供一个实体，Hibernate Search 返回类似的实体列表，每个元素带有相似度评分。
前面已经提及，在模型属性上需要增加termVector = TermVector.YES，其告诉Lucene索引时存储每个词条的频率。
基于此，相似度将在查询执行时计算：

Query moreLikeThisQuery = queryBuilder
  .moreLikeThis()
  .comparingField("productName").boostedTo(10f)
  .andField("description").boostedTo(1f)
  .toEntity(entity)
  .createQuery();
List<Object[]> results = (List<Object[]>) fullTextEntityManager
  .createFullTextQuery(moreLikeThisQuery, Product.class)
  .setProjection(ProjectionConstants.THIS, ProjectionConstants.SCORE)
  .getResultList();

2.9. 基于多个字段查询

目前为止我们一直使用onField()方法在一个字段上执行查询，实际应用中也能基于多个字段：

Query luceneQuery = queryBuilder
  .keyword()
  .onFields("productName", "description")
  .matching(text)
  .createQuery();

而且，也可以针对每个字段分别搜索。如我们可以对不同字段定义不同的加权因子（boost):

Query moreLikeThisQuery = queryBuilder
  .moreLikeThis()
  .comparingField("productName").boostedTo(10f)
  .andField("description").boostedTo(1f)
  .toEntity(entity)
  .createQuery();

2.10. 组合查询

最后Hibernate Search也支持使用不同策略实现组合查询：

SHOULD: 查询应该包括子查询匹配的元素
MUST: 查询必须包含子查询匹配的元素
MUST NOT: 查询不必包含子查询的元素

三者类似于布尔运算：and、or和not，但使用不同名称是为了强调它们也对相关性有影响。
举例：should在两个查询之间，只有有一个匹配则被返回，但如果两个都匹配，其相关性评分要高于只有一个匹配情况。

Query combinedQuery = queryBuilder
  .bool()
  .must(queryBuilder.keyword()
    .onField("productName").matching("apple")
    .createQuery())
  .must(queryBuilder.range()
    .onField("memory").from(64).to(256)
    .createQuery())
  .should(queryBuilder.phrase()
    .onField("description").sentence("face id")
    .createQuery())
  .must(queryBuilder.keyword()
    .onField("productName").matching("samsung")
    .createQuery())
  .not()
  .createQuery();

3. 总结

本文介绍了Hibernate Search的基础知识及相关配置，同时也通过示例展示各类查询功能。

Hibernate Search 教程