本文介绍在 Hibernate Search 6 中使用 Elasticsearch 后端时，如何高效地从查询结果中批量排除多个邮箱地址，涵盖 Elasticsearch 7+ 的 termsSet 方案及兼容 6.1.8 的 terms 回退方案，并强调语法差异、版本限制与性能注意事项。
本文介绍在 hibernate search 6 中使用 elasticsearch 后端时，如何高效地从查询结果中批量排除多个邮箱地址，涵盖 elasticsearch 7+ 的 `termsset` 方案及兼容 6.1.8 的 `terms` 回退方案，并强调语法差异、版本限制与性能注意事项。
在实际业务中，常需在全文检索基础上排除一组已知的干扰项（如无效邮箱、测试账号或内部员工邮箱）。你当前的代码仅能通过 .matching(filterEmailArray[0]) 排除首个邮箱，无法覆盖整个列表。根本原因在于 match() 是针对单个词条的精确匹配查询，不支持多值批量否定。
✅ 正确方案：使用 terms() 或 termsSet() 进行批量排除
Hibernate Search 6 的 Elasticsearch 扩展提供了两种语义为「字段值属于给定集合则排除」的查询方式：
▪️ 兼容 Elasticsearch 6.1.8（推荐用于旧环境）
Elasticsearch 6.x 不支持 terms_set，但完全支持 terms 查询。需将字符串数组转为 List
import java.util.Arrays;
// 假设 filterEmail = "test@example.com,admin@dev.local,bot@company.org"
String[] filterEmailArray = filterEmail.split(",");
List<string> emailFilterList = Arrays.asList(filterEmailArray);
var query = searchSession.search(User.class)
.extension(ElasticsearchExtension.get())
.select(ElasticsearchSearchProjectionFactory::source)
.where(f -> f.bool()
.must(f.match().fields("displayName", "email").matching(word).analyzer("autocomplete_search"))
.mustNot(f.terms().field("email").matching(emailFilterList).analyzer("email_indexing_exact"))
)
.sort(f -> f.score().desc());</string>
⚠️ 注意事项：
- terms 查询要求目标字段（email）必须是 keyword 类型（而非 text），否则 analyzer 将被忽略；
- Elasticsearch 6.x 对 terms 查询的 term 数量有硬性限制：默认最多 65,536 个 —— 若过滤列表超限，需分批查询或改用布尔 should/mustNot 组合（不推荐，性能差）；
- .analyzer("email_indexing_exact") 在 terms() 中仅对传入的 term 值做预处理（如小写化），不会影响索引字段本身的分析逻辑，确保与索引时使用的 analyzer 一致（如 uax_url_email tokenizer）。
▪️ 升级至 Elasticsearch 7.0+ 后的优化方案
若已升级至 ES 7+，可改用更灵活的 termsSet 查询（支持动态最小匹配数、更大容量）：
.mustNot(f.termsSet()
.field("email")
.terms(filterEmailArray) // 直接传 String[]，无需转 List
.analyzer("email_indexing_exact")
.minimumShouldMatchField("min_should_match_field") // 可选：若需动态控制匹配阈值
)
✅ 优势：termsSet 支持超过 65K 项、可结合脚本动态计算最小匹配数，且对稀疏数据更友好；但需确保映射中已为 email 字段配置 terms_set 类型支持（通常 keyword 字段默认可用）。
? 验证与调试建议
- 使用 Kibana Dev Tools 手动执行等效 DSL，确认 email 字段在索引中的实际存储格式（"email": {"type": "keyword"}）；
- 检查 analyzer 行为：通过 _analyze API 验证 "email_indexing_exact" 是否正确处理邮箱（如保留大小写、不切分 @）；
- 日志开启 Hibernate Search 的 org.hibernate.search DEBUG 级别，观察生成的 Elasticsearch 查询 JSON，确认 must_not 子句是否包含完整 terms 数组。
✅ 总结
| 场景 | 推荐方法 | 关键约束 |
|---|---|---|
| Elasticsearch ≤ 6.8 | f.terms().matching(List) | ≤ 65,536 项；字段须为 keyword |
| Elasticsearch ≥ 7.0 | f.termsSet().terms(String[]) | 无硬性数量限制；支持动态匹配策略 |
始终确保查询 analyzer 与索引 analyzer 严格一致，并优先通过字段类型和映射设计保障过滤准确性——而非依赖运行时分析逻辑修正。
