Hibernate Search手动索引异常：1500万数据仅生成7万文档求助

首先明确说：这种情况绝对不正常——正常情况下，Hibernate Search的批量索引应该为数据库中每个符合条件的实体生成一条Lucene文档，除非有明确的过滤规则或者索引过程中出现了未被察觉的错误。下面分步骤帮你排查问题：

一、先确认索引过程是否遍历了所有数据库记录 #

要搞清楚到底是Hibernate没加载所有记录，还是加载了但没生成索引文档，最直接的方式是添加进度监控：

1. 自定义进度监听器 #

修改你的索引初始化代码，添加一个MassIndexerProgressMonitor来统计加载和索引的实体数量：

public void initializeHibernateSearch() {
    logger.info("Start initialising hibernate search index.");
    try {
        FullTextEntityManager fullTextEntityManager = Search.getFullTextEntityManager(entityManager);
        fullTextEntityManager.createIndexer()
                .typesToIndexInParallel(3)
                .batchSizeToLoadObjects(50)
                .cacheMode(CacheMode.IGNORE)
                .threadsToLoadObjects(30)
                .idFetchSize(150)
                .transactionTimeout(1800)
                // 添加进度监听器
                .progressMonitor(new MassIndexerProgressMonitor() {
                    private long totalLoaded = 0;
                    private long totalIndexed = 0;

                    @Override
                    public void entitiesLoaded(int size) {
                        totalLoaded += size;
                        logger.info("已加载实体总数: " + totalLoaded);
                    }

                    @Override
                    public void entitiesIndexed(int size) {
                        totalIndexed += size;
                        logger.info("已索引实体总数: " + totalIndexed);
                    }

                    @Override
                    public void addToTotalCount(long count) {
                        logger.info("预计需要索引的实体总数: " + count);
                    }

                    @Override
                    public void indexingCompleted() {
                        logger.info("索引完成！总加载数: " + totalLoaded + ", 总索引数: " + totalIndexed);
                    }

                    // 实现其他空方法
                    @Override
                    public void documentsAdded(long increment) {}
                    @Override
                    public void documentsBuilt(int number) {}
                    @Override
                    public void purgeCompleted(long numberOfDeletedDocuments) {}
                })
                .startAndWait();
    } catch (InterruptedException e) {
        logger.error("索引初始化被中断", e);
    }
    logger.info("HIBERNATE SEARCH INDEX INITIALISED.");
}

运行后，看日志里的预计需要索引的实体总数和已加载实体总数，对比你数据库里的1500万记录数：

• 如果这两个数字远小于1500万，说明Hibernate没有从数据库取出所有记录，问题出在查询或实体映射上。
• 如果加载数是1500万，但索引数只有7万，说明Hibernate Search在索引时过滤了大部分实体。

2. 开启详细日志排查 #

配置日志框架（比如Logback/Log4j），开启Hibernate Search批量索引和SQL的调试日志，能看到更多细节：

Logback配置示例：

<configuration>
    <!-- 其他配置 -->
    <logger name="org.hibernate.search.batchindexing" level="DEBUG"/>
    <logger name="org.hibernate.search" level="INFO"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>
    <logger name="org.hibernate.type.descriptor.sql" level="TRACE"/> <!-- 可选，查看参数绑定细节 -->
</configuration>

日志里会显示批量索引执行的SQL语句，以及每一步加载/索引的数量，还能看到是否有异常抛出（比如实体加载失败、分析器错误等）。

二、常见原因排查 #

1. 实体主键映射问题 #

你的实体ID是String类型，但用了@GeneratedValue(strategy = GenerationType.AUTO)——这个组合可能有问题：

• 如果数据库的ADDRESS_ID是数值类型（比如INT/BIGINT），Hibernate无法将数值自动转换为String，会导致实体加载失败，或者加载后ID为null（主键为null的实体不会被索引）。
• 检查数据库中ADDRESSES_LOOKUP表的ADDRESS_ID字段类型，确保和实体的id字段类型一致。如果是数值类型，把实体的id改成Long或Integer，并调整@GeneratedValue策略（比如GenerationType.IDENTITY如果是自增主键）。

2. 隐性过滤规则 #

• 检查实体类是否有@Where注解（比如@Where(clause = "ACTIVE = 1")），这会过滤掉部分记录。
• 检查是否启用了Hibernate全局过滤器，比如代码中调用了session.enableFilter(...)，批量索引时会继承这些过滤规则。
• 确认@Indexed注解没有添加where参数（你的代码里没有，但可以再检查）。

3. 索引过程中的静默错误 #

虽然你的catch块只处理了InterruptedException，但批量索引过程中如果出现其他异常（比如字段分析错误、数据库连接异常），可能不会中断整个进程，但会跳过出错的实体：

• 查看日志中是否有ERROR或WARN级别的信息，比如分析器处理某个字段时抛出异常，或者SQL查询超时。
• 检查数据库中是否有异常数据（比如超大字段、特殊字符），导致分析器无法处理，进而跳过该实体的索引。

4. Luke工具查看的索引不完整 #

如果你的索引配置了分片（Hibernate Search 5支持分片），Luke可能只打开了其中一个分片，导致看到的文档数少。检查你的Hibernate Search配置，确认是否使用了单索引（默认是单索引）。

三、下一步行动 #

1. 先添加进度监听器，确认加载和索引的实体数量。
2. 对照数据库的总记录数，判断问题出在加载阶段还是索引阶段。
3. 根据日志和监听器的信息，针对性排查上述原因（主键映射、过滤规则、错误日志等）。

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