Lucene LowerCaseFilter与KeywordAnalyzer配合失效问题求助

问题背景 #

用户邮箱存在大写字母（如John.Doe@fake.com），需实现不区分大小写的全邮箱搜索——即搜索John.Doe@fake.com或john.doe@fake.com都能返回同一用户。尝试定义自定义分析器lowercaseKeywordAnalyzer并应用到邮箱字段，但LowerCaseFilter未生效。

实体类代码如下：

@Entity
@Table(name = "USER")
@Indexed
@AnalyzerDefs({
  @AnalyzerDef(
      name = "lowercaseKeywordAnalyzer",
      tokenizer = @TokenizerDef(factory = KeywordTokenizerFactory.class),
      filters = {@TokenFilterDef(factory = LowerCaseFilterFactory.class)})
})
public class UserDBVO {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  @Column(name = "USER_ID")
  @Field(name = "id", analyzer = @Analyzer(impl = KeywordAnalyzer.class))
  private long userId;

  @NotNull
  @Column(name = "FIRST_NAME")
  @Field(name = "firstName")
  private String firstName;

  @NotNull
  @Column(name = "LAST_NAME")
  @Field(name = "lastName")
  private String lastName;

  @Column(name = "EMAIL", unique = true, length = 191)
  @Field(
      name = "email",
      analyzer = @Analyzer(definition = "lowercaseKeywordAnalyzer"))
  private String email;

  // ...
}

通过Kibana执行GET /fake.model.user查看索引映射，发现email字段为text类型并带有keyword子字段，但小写转换过滤器未生效。使用版本：org.hibernate.hibernate-search-engine:5.10.13.Final-redhat-00001

解决方案 #

1. 重置索引并确认分析器注册 #

• 旧索引会保留原有映射，修改分析器后必须删除旧索引并重新生成，否则新配置不会生效。
• 确认实体类在Hibernate的扫描路径内，确保@AnalyzerDef被正确加载。

2. 查询时显式指定分析器 #

默认情况下搜索会使用字段定义的分析器，但可通过显式指定避免查询逻辑异常：

QueryBuilder qb = fullTextEntityManager.getSearchFactory()
    .buildQueryBuilder().forEntity(UserDBVO.class).get();

Query query = qb.keyword()
    .onField("email")
    .analyzer("lowercaseKeywordAnalyzer")
    .matching(searchEmail)
    .createQuery();

3. 改用Normalizer实现（推荐） #

对于邮箱这类无需分词、仅需大小写转换的场景，使用@NormalizerDef更轻量且不易出错：

@Entity
@Table(name = "USER")
@Indexed
@NormalizerDefs({
    @NormalizerDef(
        name = "lowercaseNormalizer",
        filters = {@TokenFilterDef(factory = LowerCaseFilterFactory.class)}
    )
})
public class UserDBVO {
    // ...
    @Column(name = "EMAIL", unique = true, length = 191)
    @Field(
        name = "email",
        normalizer = @Normalizer(definition = "lowercaseNormalizer"),
        analyze = Analyze.NO
    )
    private String email;
    // ...
}

该方式会将邮箱存储为小写形式，搜索时输入的内容也会经过相同的小写转换处理，实现不区分大小写匹配。

4. 验证最终索引映射 #

修改后重新生成索引，通过Kibana执行GET /fake.model.user/_mapping查看email字段配置，确认归一化/分析器设置已生效。

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