Hibernate Search 5.8.2主键查询无结果问题排查

我之前在使用Hibernate Search 5.x版本时也碰到过类似的主键查询失效问题，结合你的代码和版本特性，给你几个实用的排查方向和解决方案：

1. 确认主键查询的API是否正确使用 #

Hibernate Search中标记了@DocumentId的字段，查询时需要使用专门的ID查询API，而不是普通的字段查询。如果误用了普通字段查询，很可能会返回空结果。

正确的主键查询代码示例：

FullTextSession fullTextSession = Search.getFullTextSession(session);
QueryBuilder queryBuilder = fullTextSession.getSearchFactory()
    .buildQueryBuilder().forEntity(MAIN.class).get();

// 针对@DocumentId字段的专属查询方式
org.apache.lucene.search.Query query = queryBuilder.id().matching("PO123").createQuery();

FullTextQuery fullTextQuery = fullTextSession.createFullTextQuery(query, MAIN.class);
List<MAIN> results = fullTextQuery.list();

如果你之前是用queryBuilder.keyword().onField("poNo")这种普通字段查询方式，换成上面的ID查询API应该就能解决问题。

2. 强制重建全量索引 #

有时候主键字段没有被正确写入索引，可能是因为索引初始化不完整，或者实体更新时没有触发索引同步。这时候可以尝试手动重建全量索引：

FullTextSession fullTextSession = Search.getFullTextSession(session);
fullTextSession.createIndexer(MAIN.class).startAndWait();

重建完成后再用正确的ID查询方式测试，看看是否能返回结果。

3. 给主键字段同时添加@Field注解（可选） #

如果你需要同时支持普通字段查询主键（比如在多字段模糊搜索中包含主键），可以给主键字段同时添加@Field注解，明确指定存储和分词规则：

@Id
@DocumentId
@Field(store = Store.YES, analyze = Analyze.NO) // 主键不分词，直接存储
private String poNo;

这样配置后，无论是用ID专属查询，还是用普通的keyword().onField("poNo")查询，都能正常命中结果。

4. 检查索引的实际内容 #

如果上面的方法都没解决问题，可以用Lucene的Luke工具打开你的索引文件，直接查看MAIN实体的索引文档，确认poNo字段是否存在、值是否正确。

• 如果索引中根本没有poNo字段：说明索引构建过程中主键没有被正确处理，需要检查实体的索引触发逻辑（比如是否开启了自动索引更新）。
• 如果索引中有poNo字段但查询不到：大概率是查询方式的问题，回到第一步确认API使用是否正确。

内容的提问来源于stack exchange，提问作者USQ91