Hibernate Search 中文操作指南

22. Troubleshooting

22.1. Finding out what is executed under the hood

对于搜索查询，可以通过调用 toString() 或 queryString() 来获取 SearchQuery object 的人类可读表示形式。此外，可使用日志： org.hibernate.search.query 会在 TRACE 级别记录每个查询，然后执行该查询。

For search queries, you can get a human-readable representation of a SearchQuery object by calling toString() or queryString(). Alternatively, rely on the logs: org.hibernate.search.query will log every query at the TRACE level before it is executed.

有关被执行内容的更一般信息，请依赖于记录器：

For more general information about what is being executed, rely on loggers:

  1. org.hibernate.search.backend.lucene.infostream for Lucene.

  2. org.hibernate.search.elasticsearch.request for Elasticsearch.

22.2. Loggers

在调试使用 Hibernate Search 的应用时，以下是几个可能派的上用场的记录器：

Here are a few loggers that can be useful when debugging an application that uses Hibernate Search:

org.hibernate.search.query

适用于所有后端。

Available for all backends.

在执行之前，以 TRACE 级别记录每个搜索查询。

Logs every single search query at the TRACE level, before its execution.

org.hibernate.search.elasticsearch.request

仅适用于 Elasticsearch 后端。

Available for Elasticsearch backends only.

在执行后，以 DEBUG 或 TRACE 级别记录请求发送到 Elasticsearch 的情况。所有可用的请求和响应信息都被记录：方法、路径、执行时间、状态代码，以及完整的请求和响应。

Logs requests sent to Elasticsearch at the DEBUG or TRACE level after their execution. All available request and response information is logged: method, path, execution time, status code, but also the full request and response.

使用 DEBUG 级别仅记录非成功请求（状态代码与 2xx 不同），或使用 TRACE 级别记录每个请求。

Use the DEBUG level to only log non-success requests (status code different from 2xx), or the TRACE level to log every single request.

您可以使用 configuration property为请求和响应启用漂亮打印（换行和缩进）。

You can enable pretty-printing (line breaks and indentation) for the request and response using a configuration property.

org.hibernate.search.backend.lucene.infostream

仅适用于 Lucene 后端。

Available for Lucene backends only.

在 TRACE 级别记录卢森内部组件的低级跟踪信息。

Logs low level trace information about Lucene’s internal components, at the TRACE level.

仅启用此记录器的_TRACE_级别不够：您还必须使用 configuration property启用信息流。

Enabling the TRACE level on this logger is not enough: you must also enable the infostream using a configuration property.

22.3. Frequently asked questions

22.3.1. Unexpected or missing documents in search hits

当某些文档意外匹配或不匹配查询时，你需要有关正在执行的确切查询以及索引内容的信息。

When some documents unexpectedly match or don’t match a query, you will need information about the exact query being executed, and about the index content.

要确切了解正在执行的查询是什么，请参见 Finding out what is executed under the hood。

To find out what the query being executed looks like exactly, see Finding out what is executed under the hood.

要检查索引内容：

To inspect the content of the index:

  1. With the Elasticsearch backend, run simpler queries using either Hibernate Search or the REST APIs directly.

  2. With the Lucene backend, run simpler queries using Hibernate Search or use the Luke tool distributed as part of the Lucene binary packages.

22.3.2. Unsatisfying order of search hits when sorting by score

当按分数排序时，如果文档按预期的顺序出现，这意味着某些文档的分数比你想要的更高或更低。

When sorting by score, if the documents don’t appear in the order you expect, it means some documents have a score that is higher or lower than what you want.

了解这些分数的最佳方法只是让后端解释分数是如何计算的。返回的解释将包括对特定文档的分数如何计算的人类可读描述。

The best way to gain insight into these scores is to just ask the backend to explain how the score was computed. The returned explanation will include a human-readable description of how the score of a specific document was computed.

无论使用哪种 API，解释在性能方面相当昂贵：仅将其用于调试目的。

Regardless of the API used, explanations are rather costly performance-wise: only use them for debugging purposes.

有两种方法可检索说明：

There are two ways to retrieve explanations:

  1. If you are interested in a particular entity and know its identifier: use the explain(…​) method on the query. See explain(…​): Explaining scores.

  2. If you just want an explanation for all the top hits: use an explanation projection. See here for Lucene and here for Elasticsearch.

22.3.3. Search query execution takes too long

当搜索查询执行时间过长时，你可能需要更多有关具体执行时间和具体执行内容的信息。

When the execution of a search query is too long, you may need more information about how long it took exactly, and what was executed exactly.

要了解查询执行花费了多长时间，对搜索结果使用 took() method 。

To find out how long a query execution took, use the took() method on the search result.

要确切了解正在执行的查询是什么，请参见 Finding out what is executed under the hood。

To find out what the query being executed looks like exactly, see Finding out what is executed under the hood.