常用查询参数

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

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

defType 参数

可选

默认值：lucene

defType 参数选择 查询解析器 来处理请求中的主要查询参数 (q)。可接受的值包括：lucene (标准查询解析器)、dismax (DisMax 查询解析器)、edismax (扩展 DisMax (eDisMax) 查询解析器) 或 其他查询解析器 之一。

sort 参数

可选

默认值：score desc

sort 参数指定返回文档的顺序。

以下是一些示例排序值

示例 结果

score desc

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

price asc

按价格字段的升序排序，从最低到最高。

div(popularity,price) desc

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

inStock desc, price asc

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

categories asc

由于 categories 是一个多值字段，并且我们按升序排序，因此它会按 categories 字段的最低值升序排序。这等效于 field(categories,min) asc

更具体地说，Solr 可以根据以下内容对查询响应进行排序

  • 文档分数

  • 函数结果

  • 具有 docValues="true" (或者 indexed="true"，在这种情况下，索引项将用于在运行时动态构建 DocValue 类结构) 的单值原始字段（数字、字符串、布尔值、日期等）。

  • 单值 SortableTextField，默认情况下隐式使用 docValues="true"，允许对原始输入字符串进行排序，而不管用于搜索的分析器是什么。

  • 单值 TextField，它有一个分析器（例如 KeywordTokenizer），每个文档只生成一个词项。由于 TextField 不支持 docValues="true"，因此将在运行时动态构建类似 DocValue 的结构。

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

  • 具有 docValues="true" 或 SortableTextFields 的多值原始字段。在这种情况下，根据排序方向，为每个文档使用一个代表值。升序时，使用最小值。降序时，使用最大值。这等效于使用 2 参数 field() 函数显式排序：sort=field(name,min) asc 和 sort=field(name,max) desc。

您可以通过用逗号分隔它们来指定多个排序顺序，例如 inStock desc, price asc。当提供多个排序条件时，只有当第一个条目导致平局时才会使用第二个条目。如果存在第三个条目，则只有当第一个和第二个条目都平局时才会使用它。依此类推。

如果文档在所有显式排序标准上都相同，Solr 会使用每个文档的 Lucene 文档 ID 作为最终的决胜标准。这个内部属性在段合并和文档更新期间可能会发生变化，这可能会导致意外的结果排序变化。为了避免这种行为，用户可以在唯一或很少共享的字段（如 id）上定义额外的排序标准，以防止出现相同的情况（例如，price desc,id asc）。

排序顺序必须始终包含字段名称（或作为伪字段的 score），后跟空格（在 URL 字符串中转义为 + 或 %20），后跟排序方向（asc 或 desc，不区分大小写）。

start 参数

可选

默认值：0

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

换句话说，将 start 参数设置为除 0 之外的数字（例如 3）会导致 Solr 跳过前 3 条记录，并从偏移量标识的文档开始。

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

rows 参数

可选

默认值：10

rows 参数指定响应中要返回的完整结果中的文档数量。您可以使用 rows 参数对查询结果进行分页。

canCancel 参数

可选

默认值：false

canCancel 参数指定是否可以使用任务管理接口在执行期间取消查询。

queryUUID 参数

可选

默认值：无

对于可取消的查询，queryUUID 参数允许指定一个自定义的 UUID 来标识该查询。否则，将分配一个自动生成的 UUID。

使用 queryUUID 时，确保 UUID 的唯一性是调用者的责任。如果在原始查询 UUID 仍然活动时重用查询 UUID，则会导致第二个查询抛出异常。

建议使用所有自定义 UUID，或完全依赖系统生成 UUID，以避免 UUID 冲突。

fq (过滤查询) 参数

可选

默认值：无

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

使用 fq 参数时，请记住以下几点

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

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

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

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

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

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

  • 与所有参数一样：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 接口，则将从该查询请求一个 Collector，并用于在它们匹配主查询和所有其他过滤查询之后过滤文档。可以有多个后置过滤器；它们也按成本排序。

对于大多数查询，默认行为是 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,name,price

仅返回 id、name 和 price 字段。

id name, price

仅返回 id、name 和 price 字段。

id na* price

返回 id、name、name_exact 和 price 字段。

id na*e price

返回 id、name 和 price 字段。

id score

返回 id 字段和分数。

*

返回每个文档中的所有 stored 字段，以及任何具有 useDocValuesAsStored="true" 的 docValues 字段。这是 fl 参数的默认值。

* score

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

*,dv_field_name

返回每个文档中的所有 stored 字段，以及任何具有 useDocValuesAsStored="true" 的 docValues 字段，以及来自 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&debug=all&explainOther=id:juggernaut

上述查询允许您检查最匹配文档的评分解释信息，将其与匹配 id:juggernaut 的文档的解释信息进行比较，并确定排名不如预期的情况原因。

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

partialResults 参数

可选

默认值：true

此参数控制当查询执行达到限制时（例如，timeAllowed 或 cpuAllowed）Solr 的行为。

当此参数设置为 true (默认值) 时，即使达到限制终止进一步的查询处理，Solr 仍会尝试返回到目前为止收集的部分结果。这些结果可能以不确定的方式不完整（例如，只有一些匹配的文档、没有字段的文档、缺少 facets 或 pivots、没有拼写检查结果等）。

当此参数设置为 false 时，达到限制将生成异常，并且到目前为止收集的任何部分结果都将被丢弃。

timeAllowed 参数

可选

默认值：无

此参数指定允许搜索完成的时间量（以毫秒为单位）。如果此时间在搜索完成之前到期，将返回任何部分结果，但是诸如 numFound、facet 计数和结果 统计信息 之类的值对于整个结果集可能不准确。如果过期，如果 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 Facet 和 Analytics 组件会根据此参数放弃请求。

cpuAllowed 参数

可选

默认值：无

此参数指定允许搜索完成的 CPU 时间量（以毫秒为单位）。与 timeAllowed 不同，此参数监视执行查询的线程的实际 CPU 使用率。相同的 CPU 使用率限制应用于查询协调器以及参与分布式搜索的每个副本（尽管查询协调器首先达到此限制的可能性不大）。如果任何副本在本地超过允许的 CPU 时间，则将终止整个分布式搜索（通过取消对其他分片的请求）。

注意：相同的 CPU 限制应用于分布式查询处理的每个阶段。通常，这涉及两个或多个阶段（例如，获取顶部文档 ID、检索它们的字段，faceting、分组等可能需要其他阶段）。例如，设置 cpuAllowed=500 会为每个阶段给出最多 500 毫秒的 CPU 时间限制 - 这意味着查询的总 CPU 使用率可能会达到 cpuAllowed 值的倍数，具体取决于阶段的数量。

此处也适用 timeAllowed 参数列出的关于部分结果的所有其他考虑因素。

segmentTerminateEarly 参数

可选

默认值：false

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

如果使用了提前终止，则 segmentTerminatedEarly 标头将包含在 responseHeader 中。

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

multiThreaded 参数

可选

默认值：false

此参数设置为 true 或 false，控制 Solr 是否可以使用多个线程来满足请求。true 值目前允许 IndexSearcher 并行搜索 Lucene 的各个段，并且可以在 solr.xml 文件中自定义 indexSearcherExecutorThreads 值。在存在 &segmentsTerminateEarly=true 的情况下，此参数将被忽略（未来的工作可能会启用它）。这是一个新参数，被认为是实验性的，并且可能会在后续版本中进行更改或删除。请在我们的邮件列表中分享您对此的反馈和经验。

omitHeader 参数

可选

默认值：false

如果设置为 true，则 omitHeader 参数将从返回的结果中排除标头。标头包含有关请求的信息，例如完成请求所花费的时间。

当使用诸如 timeAllowed 和 shards.tolerant 之类的参数时，这些参数可能会导致部分结果，建议保留标头，以便可以检查 partialResults 标志，并且可以在部分结果的上下文中解释诸如 numFound、nextCursorMark、Facet 计数和结果 统计信息 之类的值。

wt 参数

可选

默认值：json

wt 参数选择 Solr 应用于格式化查询响应的响应编写器。有关响应编写器的详细描述，请参见 响应编写器。

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

logParamsList 参数

可选

默认值：所有参数

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

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

例如，您可以像这样定义：

logParamsList=q,fq

并且只会记录 'q' 和 'fq' 参数。

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

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

echoParams 参数

可选

默认值：none 或 solrconfig.xml 中的默认值

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 会使用近似命中计数（从而提供加速）。某些类型的查询或其他参数（例如，是否请求 facets）将需要精确计数。

  • 只有在首先按 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 名的相同数量的文档。