Hibernate Search 中文操作指南

Hibernate Search 的 Elasticsearch 后端与 Elasticsearch 的多个发行版兼容：

有关 Hibernate Search 的哪些未来版本应该会保留与 Elasticsearch/OpenSearch 当前兼容版本的兼容性，请参考 compatibility policy 。

如果可能，集群上运行的分发和版本会在启动时自动检测，而 Hibernate Search 会根据该信息进行调整。

使用 Amazon OpenSearch Serverless，或者当您的群集在启动时不可用时，您将必须明确配置 Hibernate Search 应该期望的版本：有关详细信息，请参见 Version compatibility。

目标版本对于 Hibernate Search 用户而言大多是透明的，但是 Hibernate Search 根据可能影响你的 Elasticsearch 发行版和版本的行为存在一些差异。以下章节详细介绍了这些差异。

Hibernate Search 的 Elasticsearch 后端与运行版本 7.10+ 或 8.x 的 Elasticsearch 集群兼容，并针对版本 7.10、7.17 或 8.14 定期进行测试。

目前，使用 Elasticsearch 不需要特定的配置且不会暗示特定的限制。

Hibernate Search 的 Elasticsearch 后端与运行版本 1.3 或 2.x 的 OpenSearch 集群兼容，并针对版本 1.3 或 2.14 定期进行测试。

目前使用 OpenSearch 无需特定配置 Hibernate Search 在使用 knn predicate与 OpenSearch 时会应用某些限制。这些限制源自 OpenSearch 的功能可用性，更多详情请参阅 this section of the documentation。

Hibernate Search 的 Elasticsearch 后端与 Amazon OpenSearch Service 兼容，并针对关键版本定期进行测试。

使用亚马逊 OpenSearch 服务需要 proprietary authentication，其中涉及额外的配置。

使用亚马逊 OpenSearch 服务意味着一项限制：在运行 Elasticsearch（而非 OpenSearch）并且仅在 7.1 或更低版本中时， closing indexes is not possible，进而 automatic schema updates ( not recommended in production) will fail when trying to update analyzer definitions。

通常 compatibility policy 不适用：孵化元素（例如类型、方法、配置属性等）的契约在后续版本中可能会以向后不兼容的方式更改，甚至可能被移除。

我们建议您使用孵化特性，以便开发团队可以收集反馈并对其进行改进，但在需要时您应做好更新依赖于这些特性的代码的准备。

Amazon OpenSearch Serverless 兼容性已实现并处于孵化中；随时对 HSEARCH-4867 提供反馈。

但是，请注意：

此外， Amazon OpenSearch Serverless也有其自身的特定限制：

升级 Elasticsearch 集群后，您的集群上仍需要某些操作：Hibernate Search 不会处理这些操作。

除此之外，Elasticsearch 的一些版本之间可能存在一些基本差异。请参阅 Elasticsearch 文档和迁移指南，以识别任何不兼容的模式更改。

在上述情况下，最简单的升级方式是手动删除索引，让 Hibernate Search 重新创建索引及其架构并 reindex your data。

以下属性配置了 Elasticsearch 主机（或主机）以发送索引请求和搜索查询：

此属性的默认值是 localhost:9200。

此属性可以设置为表示主机和端口的字符串，例如 localhost 或 es.mycompany.com:4400，或包含多个以逗号分隔的此类主机和端口字符串的字符串，或包含此类主机和端口字符串的 Collection<String>。

您可以使用此配置属性更改用于与主机通信的协议：

此属性的默认值是 http。

此属性可以设置为 http 或 https。

或者，这两种协议和主机都可以使用单个属性定义为一个或多个 URI：

此属性可以设置为表示 URI 的字符串，例如 _ http://localhost_ 或 _ https://es.mycompany.com:4400_ ，或包含逗号分隔的多重此类 URI 字符串的字符串，或包含此类 URI 字符串的 Collection<String> 。

所有 uri 必须具有相同的协议。

如果设置了 hosts 或 protocol，则无法使用。

提供的 URI 列表不得为空。

默认情况下，REST API 预计可用于根路径 (/)。例如，一个面向所有索引的搜索查询会被发送到路径 /_search。这是标准 Elasticsearch 设置所需的内容。

如果你的设置非标准，例如因为应用程序和 Elasticsearch 集群之间存在非透明的代理，你可以使用与此类似的配置：

通过以上方式，面向所有索引的搜索查询将被发送到 /my/path/_search 路径，而不是 /_search 路径。对于发送到 Elasticsearch 的所有请求，路径的前缀都类似。

在使用自动发现时，Elasticsearch 客户端会定期探测群集中的新节点，并将这些节点添加到主机列表中（请参阅 Client configuration中的 hosts）。

自动发现通过下列属性控制：

HTTP 身份验证默认情况下处于禁用状态，但是可以通过设置以下配置属性启用：

这些属性的默认值为一个空字符串。

连接到 Elasticsearch 服务器时要发送的用户名和密码。

完成配置后，Hibernate Search Elasticsearch 后端在大多数设置中会正常运作。但是，如果您需要使用 Amazon OpenSearch Service或 Amazon OpenSearch Serverless，您会发现它们需要一种专用身份验证方法： request signing。

虽然请求签名默认情况下不受支持，但是你可以使用附加的依赖项和几分配置启用它。

你需要添加此依赖项：

在类路径中添加此依赖项后，你仍需要对其进行配置。

下列配置是强制要求的：

默认情况下，Hibernate Search 将依赖 AWS SDK 的默认凭据提供者。此提供者会在各种位置（Java 系统属性、环境变量、特定于 AWS 的配置等）中查找凭据。有关默认凭据提供者工作方式的更多信息，请参阅以下内容。

或者，你可以用以下选项设置静态凭据：

Timeouts

# hibernate.search.backend.request_timeout = 30000 hibernate.search.backend.connection_timeout = 1000 hibernate.search.backend.read_timeout = 30000__request_timeout 定义执行请求时的超时时间。这包括建立连接、发送请求和读取响应所需的时间。此属性默认未定义。

connection_timeout 定义建立连接时的超时。此属性的默认值为 1000。

read_timeout 定义读取响应时的超时时间。此属性的默认值为 30000 。

这些属性需要以毫秒为单位的正数 Integer value，例如 3000。

Connection pool

hibernate.search.backend.max_connections = 20 hibernate.search.backend.max_connections_per_route = 10__max_connections 定义到 Elasticsearch 集群的最大同时连接数（包括所有主机）。此属性的默认值为 20 。

max_connections_per_route 定义与 Elasticsearch 集群的每个主机的最大并发连接数。此属性的默认值为 10。

这些属性需要一个正数 Integer value，例如 20。

Keep Alive

hibernate.search.backend.max_keep_alive = 10000__max_keep_alive 定义与 Elasticsearch 集群的连接的最长闲置时间。

需要以毫秒为单位的正数 Long value，例如 60000。

如果 Elasticsearch 集群的响应包含 Keep-Alive 标头，则有效最大空闲时间为 Keep-Alive 标头或此属性的值（如果已设置）中较低的一个。

如果未设置此属性，则仅考虑 Keep-Alive 标头，如果它不存在，则空闲连接将永久保留。

可以使用 org.apache.http.impl.nio.client.HttpAsyncClientBuilder 的实例直接配置 HTTP 客户端。

使用此 API，您可以添加拦截器、更改连接保持活动、最大连接数、SSL 密钥/信任存储设置以及许多其他客户端配置。

直接配置 HTTP 客户端需要两步：

不同发行版和版本的 Elasticsearch/OpenSearch 公开了稍有不同的 API。因此，Hibernate Search 需要了解它要通信的发行版和版本，以生成正确的 HTTP 请求。

默认情况下，Hibernate Search 将在启动时查询 Elasticsearch/OpenSearch 集群以检索此信息，并将推断出要采用的正确行为。

您可以通过将属性 hibernate.search.backend.version 设置为遵循 x.y.z-qualifier 或 <distribution>:x.y.z-qualifier 或仅 <distribution> 格式的版本字符串来强制 Hibernate Search 期望某个特定版本的 Elasticsearch/OpenSearch，其中：

例如，8、8.0、8.9、opensearch:2.9、amazon-opensearch-service 均为有效的版本字符串。

使用该平台时，您必须设置版本，并且必须简单地将它设置为 amazon-opensearch-serverless ，没有拖尾的 : 或版本号。

Hibernate Search 仍会查询 Elasticsearch/OpenSearch 集群以检测该集群的实际分布和版本（不支持的除外，即 Amazon OpenSearch Serverless），以便检查已配置的分布和版本是否与实际版本相匹配。

如有必要，您可以在启动时禁用对 Elasticsearch/OpenSearch 集群的调用，并手动提供信息。

为此，将属性 hibernate.search.backend.version_check.enabled 设置为 false。

您还必须将属性 _hibernate.search.backend.version_设置为一个版本字符串，如 previous section中所述。

在这种情况下，主版本号和次版本号（上面的格式中的 x 和 y ）是必需的，但如果它是默认值 ( elasticsearch ），则 distribution 可以省略，所有其他组件（低级、识别符）仍然是可选的。例如， 8.0 、 8.9 、 opensearch:2.9 在这种情况下都是有效的版本字符串，但 8 不够精确。

对于 Hibernate Search 中名称为 myIndex 的索引：

使用别名比直接针对索引有显著的优势：它可以在不宕机的情况下对实时应用程序进行完全重新索引，当 listener-triggered indexing 禁用 ( completely 或 partially ) 且您需要定期（例如每天）完全重新索引时尤其有用。

使用别名，您只需将读取别名（由搜索查询使用）定向到索引的旧副本，而写入别名（由文档写入使用）将被重定向到索引的新副本。在没有别名（特别是使用 no-alias 布局）的情况下，这是不可能的。

这种“零宕机”重新索引与 "blue/green" deployment 有一些共同特点，目前还没有由 Hibernate Search 本身提供。然而，您可以通过直接向 Elasticsearch 的 REST API 发出命令在您的应用程序中实现它。基本操作顺序如下：

创建一个新索引 myindex-000002。

将写别名 myindex-write 从 myindex-000001 切换到 myindex-000002。

使用 mass indexer等重新索引。

将读别名 myindex-read_从 _myindex-000001_切换到 _myindex-000002。

删除 myindex-000001 。

请注意，这仅在 Hibernate Search 映射没有更改时才有效；具有不断变化的模式的零宕机升级将更加复杂。您将在 HSEARCH-2861 和 HSEARCH-3499 中找到关于此主题的讨论。

此策略主要对旧版集群有用。

对于 Hibernate Search 中名称为 myIndex 的索引：

如果内置布局策略不符合您的要求，您可以通过两个简单步骤定义自定义布局：

例如，下面的实现将为名为 myIndex 的索引生成以下布局：

用于读写的索引或别名名称可从 metamodel中检索。

当 Hibernate Search 执行针对多个实体类型（即多个索引）的搜索查询时，它需要确定每个搜索结果的 entity type，以便将其映射回一个实体。

有多种策略用于处理此“实体类型名称解析”，每种策略各有优缺点。

此策略在后端级别设置：

此属性的默认值为 discriminator。

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

默认情况下，Hibernate Search 将 Elasticsearch 索引映射中的 dynamic 属性设置为 strict 。这意味着尝试索引映射中不存在字段的文档将导致索引失败。

如果 Hibernate Search 是唯一的客户端，这不会成问题，因为 Hibernate Search 通常仅对已声明的模式字段进行操作。对于我们需要更改此设置的其他情况，可以使用以下索引级别属性更改值。

此属性的默认值为 strict。

我们说过 Hibernate Search 通常在已声明的模式字段上工作。更确切地说，如果未定义 Dynamic fields with field templates ，它始终会这样。当定义字段模板时， dynamic 将被强制为 true ，以允许动态字段。在这种情况下， dynamic_mapping 属性的值将被忽略。

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

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

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

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

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

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

全部 built-in Elasticsearch analyzers均可立即使用，无需在 Hibernate Search 中进行任何配置：只需在 Hibernate Search 期望为分析器名称的任何位置使用其名称即可。但是，分析也可以显式配置。

只有在通过 schema management 告知 Hibernate Search 之后，它才会将配置推送到集群。

要配置 Elasticsearch 后端中的分析，您需要：

当启动时，Hibernate Search 将调用此实现的 configure 方法，而配置器能够充分利用 DSL 定义 analyzers and normalizers。

# To set the default configurer for all indexes: hibernate.search.backend.analysis.configurer = class:com.mycompany.MyAnalysisConfigurer # To assign a specific configurer to a specific index: hibernate.search.backend.indexes.<index-name>.analysis.configurer = class:com.mycompany.MySpecificAnalysisConfigurer # To set the default configurer for all indexes: hibernate.search.backend.analysis.configurer = class:com.mycompany.MyAnalysisConfigurer # To assign a specific configurer to a specific index: hibernate.search.backend.indexes.<index-name>.analysis.configurer = class:com.mycompany.MySpecificAnalysisConfigurer 如果将特定配置器分配给索引，则该索引将忽略默认配置器：只考虑来自特定配置器的定义。

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

Elasticsearch 后端带有几个内置分析器。确切的列表取决于 Elasticsearch 的版本，且可在 here 中找到。

无论 Elasticsearch 版本如何，名称在 org.hibernate.search.engine.backend.analysis.AnalyzerNames 中列为常量的分析器始终可用：

default

@FullTextField 默认使用的分析器。

这只是 standard 的别名。

standard

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

simple

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

whitespace

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

stop

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

keyword

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

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

请考虑改用 @KeywordField 。

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

传递给配置器的上下文采用了 DSL 来定义分析器和规范化器：

也可以向带参数的内置分析器分配一个名称：

要了解有哪些分析器、字符过滤器、分词器和分词器过滤器可用，请参阅文档：

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

如同其他 built-in analyzer 一样，通过定义同名 custom analyzer，可以替代默认分析器：

如果使用设置 index.max_result_window，则 Hibernate Search 将使用此值限制返回的命中数大小，如果用户未在查询中定义限制。在这种情况下，如果 Hibernate Search 注意到还有更多结果，则将记录警告。

当写入索引时，Elasticsearch 依靠 transaction log 来确保更改（即使是未提交的更改）在 REST API 调用返回后始终是安全的。

因此，“提交”的概念对 Elasticsearch 后端并不重要，提交要求在很大程度上无关紧要。

当从索引中读取时，Elasticsearch 依靠周期性刷新的索引读取器，这意味着搜索查询将返回稍过时的结果，除非强制刷新：这称为 near-real-time 行为。

默认情况下，索引读取器每秒都会刷新一次，但可以通过索引设置在 Elasticsearch 端进行自定义：请参阅 refresh_interval 中 this page 处的设置。

使用 Elasticsearch 后端， scrolls 会受到超时限制。如果 next() 没有长时间被调用（默认值为 60 秒），则滚动将自动关闭，且下次调用 next() 时会失败。

在后端级别使用以下配置属性配置超时（以秒为单位）：

此属性的默认值为 60。

使用 Elasticsearch 后端， fetching results 可能会导致部分分片失败，即一些分片将无法产生结果，而其他分片会成功。在这种情况中，Elasticsearch 集群将生成一个响应，该响应的状态代码为成功状态代码，但将包含关于失败分片的其他信息，以及它们失败的原因。

默认情况下，Hibernate Search 将在获取结果时检查是否有任何分片失败，如果失败将抛出一个异常。

使用后端级别的以下配置属性来更改默认行为：

该属性的默认值为 false。