常见查询参数

多个查询解析器共享受支持的查询参数。

以下部分介绍了 Solr 的常见查询参数，这些参数受 搜索请求处理程序 支持。

defType 参数

defType 参数选择 Solr 应使用该参数来处理请求中的主查询参数 (q)。例如

defType=dismax

如果未指定 defType 参数，则默认情况下使用 标准查询解析器。（例如，defType=lucene）

sort 参数

sort 参数按升序 (asc) 或降序 (desc) 排列搜索结果。该参数可用于数字或字母内容。方向可以用全小写或全大写字母输入（即，asc 和 ASC 都被接受）。

Solr 可以根据以下内容对查询响应进行排序

  • 文档评分

  • 函数结果

  • 任何基元字段（数字、字符串、布尔值、日期等）的值，该字段具有 docValues="true"（或 multiValued="false" 和 indexed="true"，在这种情况下，索引项将用于在运行时动态构建类似 DocValue 的结构）

  • SortableTextField，它默认隐式使用 docValues="true"，以便对原始输入字符串进行排序，而不管用于搜索的分析器如何。

  • 使用分析器（例如 KeywordTokenizer）的单值 TextField，该分析器仅生成每个文档一个术语。TextField 不支持 docValues="true"，但将在运行时动态构建类似 DocValue 的结构。

    • 注意：如果您希望能够对您希望标记其内容以方便搜索的字段进行排序，请在模式中使用 copyField 指令来克隆该字段。然后在该字段上搜索并在其克隆上排序。

对于原始字段或 SortableTextFields，即 multiValued="true"，在排序时用于每个文档的代表值取决于排序方向：在升序 (asc) 排序中使用每个文档中的最小值，而在降序 (desc) 排序中使用每个文档中的最大值。此默认行为等效于使用 2 个参数 field() 函数显式排序：sort=field(name,min) asc 和 sort=field(name,max) desc

下表说明了 Solr 如何响应 sort 参数的各种设置。

示例 结果

如果省略 sort 参数，则执行排序，就像将参数设置为 score desc 一样。

score desc

按从最高分到最低分的降序排列。

price asc

按价格字段升序排列

div(popularity,price) desc

按函数 popularity / price 结果的降序排列

inStock desc, price asc

按 inStock 字段的内容降序排列，然后当多个文档的 inStock 字段值相同时，按价格字段的内容升序排列这些结果。

categories asc, price asc

按 (多值) categories 字段的最低值升序排列，然后当多个文档具有相同的最低 categories 值时，按价格字段的内容升序排列这些结果。

关于 sort 参数的参数

  • 排序顺序必须包括一个字段名称（或 score 作为伪字段），后跟空格（在 URL 字符串中转义为 + 或 %20），后跟排序方向（asc 或 desc）。

  • 可以使用此语法用逗号分隔多个排序顺序：sort=<field name><direction>,<field name><direction>],…​

    • 当提供多个排序条件时，仅当第一个条目导致平局时，才会使用第二个条目。如果存在第三个条目，则仅当第一个和第二个条目打平时才会使用它。以此类推。

    • 如果文档与所有显式排序条件相匹配，Solr 将使用每个文档的 Lucene 文档 ID 作为最终的决胜条件。此内部属性在分段合并和文档更新期间可能会发生变化，这可能导致意外的结果排序更改。希望避免此行为的用户可以在唯一或很少共享的字段（例如 id）上定义其他排序条件，以防止出现平局（例如，price desc,id asc）。

start 参数

指定时，start 参数指定查询结果集中的偏移量，并指示 Solr 从此偏移量开始显示结果。

默认值为 0。换句话说，默认情况下，Solr 返回没有偏移量的结果，从结果本身开始的地方开始。

将 start 参数设置为其他数字（例如 3）会导致 Solr 跳过前面的记录，并从偏移量标识的文档开始。

您可以将 start 参数以这种方式用于分页。例如，如果将 rows 参数设置为 10，则可以通过将 start 设置为 0 来显示三个连续的结果页面，然后重新发出相同的查询并将 start 设置为 10，然后再次发出查询并将 start 设置为 20。

rows 参数

您可以使用 rows 参数对查询结果进行分页。该参数指定 Solr 应一次向客户端返回的完整结果集中文档的最大数量。

默认值为 10。也就是说，默认情况下，Solr 在响应查询时一次返回 10 个文档。

canCancel 参数

此参数定义是否可以使用 任务管理界面在执行期间取消此查询。

queryUUID 参数

对于可取消的查询，这允许指定一个自定义 UUID 来标识查询。如果指定了 canCancel 但未设置 queryUUID，则将为查询分配一个自动生成的 UUID。

如果指定了 queryUUID，则此 UUID 将用于标识查询。请注意，如果使用 queryUUID，则确保 UUID 唯一性的责任在于调用方。如果在原始查询 UUID 仍然处于活动状态时重新使用了查询 UUID，则会导致为第二个查询引发异常。

建议用户使用所有自定义 UUID 或完全依赖系统生成 UUID。混合两者会导致 UUID 冲突。

fq（筛选查询）参数

fq 参数定义了一个查询，该查询可用于限制可返回的文档超集，而不会影响分数。它对于加速复杂查询非常有用，因为使用 fq 指定的查询独立于主查询进行缓存。当后续查询使用相同的过滤器时，将命中缓存，并且会从缓存中快速返回过滤器结果。

在使用 fq 参数时，请记住以下内容

  • fq 参数可以在查询中多次指定。只有当文档位于由该参数的每个实例产生的文档集的交集中时，才会将文档包含在结果中。在下面的示例中，只有受欢迎程度大于 10 且部分为 0 的文档才会匹配。

    fq=popularity:[10 TO *]&fq=section:0

  • 过滤器查询可能涉及复杂的布尔查询。上述示例也可以写成一个带有两个必选子句的单个 fq，如下所示

    fq=+popularity:[10 TO *] +section:0

  • 每个过滤器查询的文档集独立缓存。因此，关于前面的示例：如果这些子句经常一起出现，请使用包含两个必选子句的单个 fq；如果它们相对独立，请使用两个单独的 fq 参数。（要了解如何调整缓存大小并确保确实存在过滤器缓存，请参阅 缓存。）

  • 还可以使用 filter(condition) 语法 在 fq 中单独缓存子句，并且 - 除其他外 - 实现缓存过滤器查询的并集。

  • 与所有参数一样：URL 中的特殊字符需要正确转义并编码为十六进制值。可以使用在线工具来帮助您进行 URL 编码。例如： http://meyerweb.com/eric/tools/dencoder/.

cache 本地参数

Solr 默认情况下在 过滤器缓存 中缓存过滤器查询的结果。要禁用它，请使用布尔 cache 本地参数，例如 fq={!geofilt cache=false}…​。当您认为查询不太可能重复时，请执行此操作。

非缓存过滤器查询还支持 cost 本地参数，以提供有关其评估顺序的提示。这允许您在昂贵的非缓存过滤器之前对不太昂贵的非缓存过滤器进行排序。在 Lucene 层中，如果查询具有 TPI，这会映射到 TwoPhaseIterator.matchCost。

后置过滤器：对于非常昂贵的过滤器，如果 cache=false 且 cost>=100，且 查询实现了 PostFilter 接口，则将从该查询请求一个收集器，并用于在文档与主查询和所有其他过滤器查询匹配后对其进行过滤。可以有多个后置过滤器；它们也按成本排序。

对于大多数查询，默认行为是 cost=0，但某些类型的查询（例如 {!frange}）默认为 cost=100，因为当用作 PostFilter 时它们最有效。

这是 3 个常规过滤器的示例，其中每个过滤器生成的所有匹配文档都会预先计算并独立缓存

q=some keywords
fq=quantity_in_stock:[5 TO *]
fq={!frange l=10 u=100}mul(popularity,price)
fq={!frange cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)

这些是在不缓存的情况下运行的相同过滤器。quantity_in_stock 字段上的简单范围查询将与主查询并行运行，就像传统的 Lucene 过滤器一样，而 2 个 frange 过滤器将仅针对每个文档进行检查，该文档已与主查询和 quantity_in_stock 范围查询匹配 — 首先将检查更简单的 mul(popularity,price)（因为它隐含 cost=100），并且仅当它匹配时，才会检查最终非常复杂的过滤器（其较高的 cost=200）。

q=some keywords
fq={!cache=false}quantity_in_stock:[5 TO *]
fq={!frange cache=false l=10 u=100}mul(popularity,price)
fq={!frange cache=false cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)

fl（字段列表）参数

fl 参数将查询响应中包含的信息限制为指定字段列表。这些字段必须为 stored="true" 或 docValues="true"`.`

字段列表可以指定为用空格或逗号分隔的字段名称列表。字符串“score”可用于指示应将每个文档针对特定查询的分数作为字段返回。通配符 * 会选择文档中所有 stored="true" 或 docValues="true" 且 useDocValuesAsStored="true"（在启用 docValues 时为默认值）的字段。将通配符与字段名称结合使用，以形成 glob 模式，用于匹配多个字段名称。

您还可以将伪字段、函数和转换器添加到字段列表请求中。

此表显示了一些有关如何使用 fl 的基本示例

字段列表 结果

id name price

仅返回 id、name 和 price 字段。

id、名称、价格

仅返回 id、name 和 price 字段。

id 名称、价格

仅返回 id、name 和 price 字段。

id na* 价格

返回 id、名称、name_exact 和价格字段。

id na*e 价格

返回 id、名称和价格字段。

id 分数

返回 id 字段和分数。

*

返回每个文档中的所有 存储字段，以及所有 docValues 字段（其中 useDocValuesAsStored="true"）。这是 fl 参数的默认值。

* 分数

返回每个文档中的所有字段，以及每个字段的分数。

*,dv_field_name

返回每个文档中的所有 存储字段，以及所有 docValues 字段（其中 useDocValuesAsStored="true"），以及 dv_field_name 中的 docValues，即使其中 useDocValuesAsStored="false"。

带有 fl 的函数

函数查询可以针对结果中的每个文档计算，并作为伪字段返回

fl=id,title,product(price,popularity)

带有 fl 的文档转换器

文档转换器可用于修改查询结果中关于每个文档返回的信息

fl=id,title,[explain]

字段名称别名

您可以通过为字段、函数或转换器添加 displayName: 值前缀来更改响应中用于该字段、函数或转换器的键。

例如，why_score 是下面的显示名称

fl=id,sales_price:price,secret_sauce:prod(price,popularity),why_score:[explain style=nl]
{
"response": {
    "numFound": 2,
    "start": 0,
    "docs": [{
        "id": "6H500F0",
        "secret_sauce": 2100.0,
        "sales_price": 350.0,
        "why_score": {
            "match": true,
            "value": 1.052226,
            "description": "weight(features:cache in 2) [DefaultSimilarity], result of:",
            "details": [{
                "..."
}]}}]}}

debug 参数

debug 参数可以指定多次，并支持以下参数

  • debug=query：仅返回有关查询的调试信息。

  • debug=timing：返回有关查询处理时间长度的调试信息。

  • debug=results：返回有关分数结果的调试信息（也称为“解释”）。

    • 默认情况下，分数解释作为大字符串值返回，使用换行符和制表符缩进以实现结构和可读性，但可以指定附加的 debug.explain.structured=true 参数，以将此信息作为嵌套数据结构返回，该数据结构是 wt 请求的响应格式的本机结构。

  • debug=all：返回关于请求请求的所有可用调试信息。另一种用法是 debug=true。

为了向后兼容 Solr 的旧版本，debugQuery=true 可以指定为指示 debug=all 的另一种方法。

默认行为是不包含调试信息。

explainOther 参数

explainOther 参数指定一个 Lucene 查询，以便标识一组文档。如果包含此参数并将其设置为非空白值，则查询将返回调试信息，以及与主查询（由 q 参数指定）相关的匹配 Lucene 查询的每个文档的“解释信息”。例如

q=supervillains&debugQuery=on&explainOther=id:juggernaut

上面的查询允许您检查匹配度最高的文档的评分解释信息，将其与匹配 id:juggernaut 的文档的解释信息进行比较，并确定排名为何与您的预期不同。

此参数的默认值为空白，这会导致不返回额外的“解释信息”。

timeAllowed 参数

此参数指定完成搜索允许的时间量（以毫秒为单位）。如果此时间在搜索完成之前到期，则将返回任何部分结果，但诸如 numFound、facet 计数和结果 stats 的值可能不适用于整个结果集。在到期的情况下，如果 omitHeader 未设置为 true，则响应头包含一个名为 partialResults 的特殊标志。当将 timeAllowed 与 cursorMark 结合使用，并且 partialResults 标志存在时，结果集中可能跳过了一些匹配的文档。此外，如果 partialResults 标志存在，则 cursorMark 可以匹配 nextCursorMark，即使可能还有更多结果

{
  "responseHeader": {
    "status": 0,
    "zkConnected": true,
    "partialResults": true,
    "QTime": 20,
    "params": {
      "q": "*:*"
    }
  },
  "response": {
    "numFound": 77,
    "start": 0,
    "docs": [ "..." ]
  }
}

仅在以下时间检查此值

  1. 查询扩展，和

  2. 文档收集

  3. Doc Values 读取

由于此检查是定期执行的，因此在请求被中止之前可以处理请求的实际时间将略大于或等于 timeAllowed 的值。如果请求在其他阶段、自定义组件等中消耗更多时间，则不希望此参数中止请求。常规搜索、JSON 分面和分析组件将根据此参数放弃请求。

segmentTerminateEarly 参数

此参数可以设置为 true 或 false。

如果设置为 true，并且此集合的 mergePolicyFactory 是 SortingMergePolicyFactory，它使用与为此查询指定的 sort 参数 兼容的 sort 选项，那么 Solr 将能够按每个段跳过绝对不是当前结果页候选的文档。

如果使用早期终止，则 responseHeader 中将包含 segmentTerminatedEarly 标头。

类似于使用 timeAllowed 参数，当发生早期段终止时，诸如 numFound、分面 计数和结果 统计信息 之类的值可能对整个结果集不准确。

此参数的默认值为 false。

omitHeader 参数

此参数可以设置为 true 或 false。

如果设置为 true，此参数将从返回的结果中排除标头。标头包含有关请求的信息，例如完成请求所花费的时间。此参数的默认值为 false。当使用诸如 timeAllowed 和 shards.tolerant 之类的参数时，这可能导致部分结果，建议保留标头，以便可以检查 partialResults 标志，并且诸如 numFound、nextCursorMark、分面 计数和结果 统计信息 之类的值可以在部分结果的上下文中进行解释。

wt 参数

wt 参数选择 Solr 应使用该参数来格式化查询响应的响应编写器。有关响应编写器的详细说明，请参阅 响应编写器。

如果您未在查询中定义 wt 参数，则 JSON 将作为响应的格式返回。

logParamsList 参数

默认情况下，Solr 会记录每个请求上的所有查询参数。此参数允许用户通过指定应记录的参数名称的以逗号分隔的“允许列表”来覆盖此行为。这可能有助于仅将日志记录控制到对您的组织而言重要的那些参数。

logParamsList 仅控制查询参数的日志记录。它不适用于请求路径、正文等中指定的参数。

例如，您可以这样定义

logParamsList=q,fq

并且仅记录“q”和“fq”参数。

如果不需要记录任何参数，则可以将 logParamsList 发送为空（即 logParamsList=）。

此参数不仅适用于查询请求，还适用于对 Solr 的任何类型的请求。

echoParams 参数

echoParams 参数控制响应头中包含哪些有关请求参数的信息。

echoParams 参数接受以下值

  • explicit：仅实际请求中包含的参数将添加到响应头的 params 部分。

  • all：包含有助于查询的所有请求参数。这将包括 solrconfig.xml 中找到的请求处理程序定义中定义的所有内容以及请求中包含的参数，以及 _ 参数。如果某个参数包含在请求处理程序定义和请求中，它将多次出现在响应头中。

  • none：完全删除响应头的 params 部分。响应中将不提供有关请求参数的任何信息。

默认值为 none，尽管许多 solrconfig.xml 处理程序将默认值设置为 explicit。以下是一个 JSON 响应示例，其中 echoParams 参数在该 SearchHandler 的默认值中设置，因此它本身不会回显，但仅从请求本身回显三个参数 - q、wt 和 indent

{
  "responseHeader": {
    "status": 0,
    "QTime": 0,
    "params": {
      "q": "solr",
      "indent": "true",
      "wt": "json",
      "_": "1458227751857"
    }
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "docs": []
  }
}

如果发送类似请求，将 echoParams=all 添加到上一个示例中使用的三个参数，则会发生这种情况

{
  "responseHeader": {
    "status": 0,
    "QTime": 0,
    "params": {
      "q": "solr",
      "df": "text",
      "indent": "true",
      "echoParams": "all",
      "rows": "10",
      "wt": "json",
      "_": "1458228887287"
    }
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "docs": []
  }
}

minExactCount 参数

使用此参数时，Solr 将至少准确地统计此值之前的命中次数。之后，Solr 可以跳过分数不够高而无法进入前 N 名的文档。这可以极大地提高搜索查询的性能。另一方面，使用此参数时，numFound 可能不准确，而可能是一个近似值。所有响应中都包含 numFoundExact 布尔属性，指示 numFound 值是准确值还是近似值。如果它是一个近似值，则查询的实际命中次数保证大于或等于 numFound。

有关近似文档计数和 minExactCount 的更多信息

  • 响应中返回的文档保证是得分最高的文档。此参数不会使 Solr 跳过响应中要返回的文档，它只会允许 Solr 跳过计数文档，虽然它们与查询匹配，但其分数低到不足以进入前 N 名。

  • 提供 minExactCount 并不保证 Solr 将使用近似命中计数（从而提供加速）。某些类型的查询或其他参数（例如，如果请求了分组）将需要准确计数。

  • 近似计数仅可在先按 score desc 排序时使用（这是 Solr 中的默认排序）。其他字段可以在 score desc 之后使用，但如果在分数之前使用了任何其他类型的排序，则不会应用近似值。

  • 在多个分片上执行分布式查询时，每个分片将准确地统计命中次数，直到 minExactCount（这意味着查询可能命中 numShards * minExactCount 文档，而响应中的 numFound 仍然准确）例如

q=quick brown fox&minExactCount=100&rows=10
"response": {
    "numFound": 153,
    "start": 0,
    "numFoundExact": false,
    "docs": [{"doc1"}]
}

由于 numFoundExact=false，我们知道与查询匹配的文档数大于或等于 153。如果我们为 minExactCount 指定更高的值

q=quick brown fox&minExactCount=200&rows=10
"response": {
    "numFound": 163,
    "start": 0,
    "numFoundExact": true,
    "docs": [{"doc1"}]
}

在这种情况下，我们知道 163 是查询的确切命中数。两个查询都必须在前 10 名中返回相同数量的文档。