Hibernate Search 中文操作指南

local-filesystem 目录类型会将每个索引存储在配置的文件系统目录的一个子目录下。

特别是，它们不应该在多个 Hibernate Search 实例之间共享。即使网络共享允许共享索引的原始内容，从多个 Hibernate Search 使用相同的索引文件也需要更多内容：非独占锁，从一个节点向另一个节点路由写入请求…​ 这些附加功能在 local-filesystem 目录中根本不可用。

如果您需要在多个 Hibernate Search 实例之间共享索引，则 Elasticsearch 后端将是更好的选择。有关详细信息，请参阅 Architecture 。

local-heap 目录类型会将索引存储在本地 JVM 堆中。

因此，关闭 JVM 时，包含在 local-heap 目录中的索引将丢失。

仅在测试配置中使用小型索引和低并发的情况下，才提供此目录类型，在这种情况下，它可以稍微提高性能。在需要使用较大索引和/或高并发的情况下， filesystem-based directory 将达到更好的性能。

除 locking strategy 之外，local-heap 目录不会提供任何特定选项。

为了写入索引，Lucene 需要获取一个锁以确保没有其他应用程序实例同时写入同一索引。每个目录类型都带有默认锁定策略，在大多数情况下都足够好。

对于需要其他锁定策略的那些（非常）罕见的情况，Hibernate Search 公开了一个配置属性：

有以下策略可用：

此策略仅适用于基于文件系统的目录。

参见 org.apache.lucene.store.SimpleFSLockFactory。

这是 local-filesystem 目录类型的默认策略。

该实现已知存在 NFS 问题：应该避免在网络共享上使用。

此策略仅适用于基于文件系统的目录。

参见 org.apache.lucene.store.NativeFSLockFactory。

这是 local-heap 目录类型的默认策略。

请参阅 org.apache.lucene.store.SingleInstanceLockFactory。

请参阅 org.apache.lucene.store.NoLockFactory。

在 Lucene 后端中，分片默认处于禁用状态，但可以通过选择分片策略来启用它。有多个策略可用：

hash

# To configure the defaults for all indexes: hibernate.search.backend.sharding.strategy = hash hibernate.search.backend.sharding.number_of_shards = 2 # To configure a specific index: hibernate.search.backend.indexes.<index-name>.sharding.strategy = hash hibernate.search.backend.indexes.<index-name>.sharding.number_of_shards = 2_The _hash 策略需要通过 number_of_shards 属性设置指定数量的分片。

此策略将设置一个显式配置的分片数，从 0 到所选号码减一（例如，对于 2 个分片，将有分片“0”和分片“1”）。

在路由时，将对路由健进行哈希以将其分配给某个分片。如果路由键为 null，则将使用文档 ID。

当没有明确的路由键 configured in the mapping，或者当路由键具有大量需要减少到较小数量的可能值（例如，“所有整数”），此策略适用。

explicit

# To configure the defaults for all indexes: hibernate.search.backend.sharding.strategy = explicit hibernate.search.backend.sharding.shard_identifiers = fr,en,de # To configure a specific index: hibernate.search.backend.indexes.<index-name>.sharding.strategy = explicit hibernate.search.backend.indexes.<index-name>.sharding.shard_identifiers = fr,en,de_The _explicit 策略需要通过 shard_identifiers 属性设置分片标识符列表。标识符必须作为包含以逗号分隔的多 分片标识符的字符串提供，或者作为包含分片标识符的 Collection<String> 提供。分片标识符可以是任何字符串。

此策略将为每个配置的分片标识符设置一个分片。

在路由时，将验证路由键以确保它与分片标识符完全匹配。如果匹配，则文档将被路由到该分片。如果不匹配，则将引发异常。路由键不能为 null，并且将忽略文档 ID。

当存在明确的路由键 configured in the mapping，且该路由键具有在启动应用程序之前已知的有限数量的可能值时，此策略适用。

在某些情况下，特别是当使用 explicit 分片策略时，可能需要以稍有不同的方式配置某些分片。例如，其中一个分片可能包含大量但很少访问的数据，这些数据应该存储在不同的驱动器上。

可以通过为特定分片添加配置属性来实现此目的：

按每个分片覆盖主要用于与 directory 和 I/O 相关的设置。

有效的片标识符取决于分片策略：

根据在当前会话中定义的租户 ID，多租户功能得到支持并且会以透明的方式处理：

如果在映射器中启用了多租户，则在后端中会自动启用多租户，例如，如果 a multi-tenancy strategy is selected in Hibernate ORM，或者如果 multi-tenancy is explicitly configured in the Standalone POJO mapper。

但是，可以手动启用多租户功能。

多租户策略是在后端级别设置的：

有关可用策略的详细信息，请参阅以下小节。

Analysis 是由分析器执行的文本处理，包括在索引编制（文档处理）时和在搜索（查询处理）时。

Lucene 后端会自带一些 default analyzers，但也可以明确配置分析。

要在 Lucene 后端中配置分析，你需要：

Hibernate Search 将在启动时调用此实现的 configure 方法，配置器将能够利用 DSL 来定义 analyzers and normalizers，甚至（对于更高级的用法）定义 similarity。请参见下面的示例。

开箱即用的内置分析器不需要显式配置。如有必要，通过用相同名称定义自己的分析器可以覆盖它们。

Lucene 后端附带一系列内置分析器；其名称在 org.hibernate.search.engine.backend.analysis.AnalyzerNames 中的常量中列出：

default

@FullTextField 默认使用的分析器。

默认实现：org.apache.lucene.analysis.standard.StandardAnalyzer。

默认行为：首先，使用标准标记化器进行标记化，该标记化器遵循 Unicode 文本分段算法的单词分隔规则，如 Unicode Standard Annex #29中指定的那样。然后，将每个标记小写。

standard

默认实现：org.apache.lucene.analysis.standard.StandardAnalyzer。

默认行为：首先，使用标准标记化器进行标记化，该标记化器遵循 Unicode 文本分段算法的单词分隔规则，如 Unicode Standard Annex #29中指定的那样。然后，将每个标记小写。

simple

默认实现： org.apache.lucene.analysis.core.SimpleAnalyzer 。

默认行为：首先在非字母字符处拆分文本。然后将每个单词转换为小写。

whitespace

默认实现： org.apache.lucene.analysis.core.WhitespaceAnalyzer 。

默认行为：在空格字符处拆分文本。不更改单词。

stop

默认实现： org.apache.lucene.analysis.core.StopAnalyzer 。

默认行为：首先在非字母字符处拆分文本。然后将每个单词转换为小写。最后，删除英语停用词。

keyword

默认实现： org.apache.lucene.analysis.core.KeywordAnalyzer 。

默认行为：不以任何方式更改文本。

通过这个分析器，全文字段的行为将类似于关键字字段，但功能更少：例如，没有词组聚合。

请考虑改用 @KeywordField 。

Lucene 后端不提供任何内置规范化器。

使用 @FullTextField 但未明确指定分析器时的默认分析器名为 default 。

像任何其他 built-in analyzer 一样，可以通过定义具有相同名称的 custom analyzer 来覆盖默认分析器：

搜索时，将根据在索引时间记录的统计信息使用特定公式为文档分配分数。这些统计信息和公式由一个称为“相似性”的单个组件定义，实现 Lucene 的 org.apache.lucene.search.similarities.Similarity 接口。

默认情况下，Hibernate Search 使用 BM25Similarity 及其默认参数 (k1 = 1.2, b = 0.75)。这应该可以在大多数情况下提供令人满意的评分。

如有高级需求，可以在分析配置器中设置自定义 Similarity，如下所示。

还可以在网上找到有用的资源，例如在 Elasticsearch 的文档中。

在 Lucene 术语中，@{24} 是当缓存在索引编写器中的更改被推送到索引本身时，以便崩溃或断电不再会导致数据丢失。

某些操作非常重要，并且总是在被认为完成之前提交。对于由 listener-triggered indexing 触发的更改（除非 configured otherwise），以及对于大规模操作（例如 purge）来说，情况就是这样。当遇到此类操作时，将立即执行提交，以保证仅在所有更改都安全地存储在磁盘上后才将该操作视为完成。

但是， mass indexer 贡献的更改等其他操作或在 indexing 使用 async synchronization strategy 时，不一定预期立即提交。

就性能而言，提交可能是一项昂贵的操作，这就是 Hibernate Search 尝试不要太频繁地提交的原因。默认情况下，当不立即提交的更改应用于索引时，Hibernate Search 将延迟提交一秒钟。如果在那一秒钟内应用了其他更改，则它们将包含在相同的提交中。这极大地减少了在写入密集型场景（例如 mass indexing）中的提交数量，从而导致了更好的性能。

可以通过设置提交间隔（以毫秒为单位）来控制 Hibernate Search 执行提交的频率：

此属性的默认值为 1000。

默认情况下，提交间隔可能只会提升 mass indexer 的吞吐量。如果你希望由 explicitly or by listeners 触发的更改也能从中受益，则需要选择非默认 synchronization strategy ，以免在每次更改后都需要进行提交。

在 Lucene 术语中，当打开一个新索引阅读器时，refresh 会进行操作，这样可以是下一个搜索查询考虑索引的最新更改。

在性能方面，刷新可能是一项昂贵的操作，这就是 Hibernate Search 尝试不要过频繁地刷新的原因。索引读取器在每个搜索查询时都会刷新，但前提是自上次刷新以来发生了写操作。

在写密集型场景中，每次写操作后刷新仍然过于频繁，这时可以降低刷新频率，从而通过设置以毫秒为单位的刷新间隔提高读取吞吐量。当将其设置为大于 0 的值时，将不再在每个搜索查询时刷新索引读取器：如果搜索查询开始时刷新在 X 毫秒之前发生，则即使索引读取器可能已过时，也不会刷新它。

刷新间隔可以通过以下方式设置：

此属性的默认值为 0。

Hibernate Search 用来写索引的 Lucene’s IndexWriter，公开了多个设置，可以对其进行微调以更好地适配你的应用程序，最终获得更好的性能。

Hibernate Search 通过索引级别的具有 io.writer. 前缀的配置属性公开这些设置。

以下是所有索引作者设置的列表。它们都可以通过配置属性以类似的方式设置；例如，io.writer.ram_buffer_size 可以像这样设置：

表 12. IndexWriter 的配置属性

Lucene 索引不会存储在单个连续的文件中。相反，每次刷新索引会生成一个小文件，包含加入到索引中的所有文档。该文件被称为“段”。在包含过多段的索引上，搜索可能会更慢，所以 Lucene 会定期合并小段以创建更少且更大的段。

Lucene 的合并行为通过 MergePolicy 控制。Hibernate Search 使用 LogByteSizeMergePolicy，它公开了多个设置，可以对其进行微调以更好地适配你的应用程序，最终获得更好的性能。

以下是所有合并设置的列表。它们都可以通过配置属性以类似的方式设置；例如，io.merge.factor 可以像这样设置：

表 13. 与合并相关的配置属性

首先，考虑合并段是指将段与另一个现有段组合在一起形成一个更大的段。 io.merge.max_size 是合并之前的段允许的最大大小，因此新合并后的段可能达到其两倍大小。

其次，合并选项不会影响索引写入程序在合并之前创建的段的初始大小。此大小可以用设置 io.writer.ram_buffer_size 来限制，但 Lucene 依靠估算值来实施此限制；当这些估算值出现偏差时，新创建的段可能会略大于 io.writer.ram_buffer_size 。

因此，例如，为了相当自信地确保没有文件增长到大于 15MB，请使用类似这样的设置：

hibernate.search.backend.io.writer.ram_buffer_size = 10 hibernate.search.backend.io.merge.max_size = 7 hibernate.search.backend.io.merge.max_forced_size = 7 hibernate.search.backend.io.writer.ram_buffer_size = 10 hibernate.search.backend.io.merge.max_size = 7 hibernate.search.backend.io.merge.max_forced_size = 7

即使是针对 bug 修复（微）版本，升级 Hibernate Search 也可能需要升级 Lucene，这可能会导致 Lucene 中中断 API 更改。

如果出现此情况，您将需要更改应用程序代码来应对这些更改。

Lucene 支持缓存低级别命中，即缓存与给定 org.apache.lucene.search.Query 在给定索引段中匹配的文档列表。

在读密集型场景中，该缓存很有用，在这种场景中，相同的查询会在同一索引上执行很频繁，而且很少会写到索引中。

Hibernate Search 会在启动时调用此实现的 configure 方法，配置人员将能够利用 DSL 来定义 org.apache.lucene.search.QueryCache 和 org.apache.lucene.search.QueryCachingPolicy。