查询和排序选项

单独使用查询字符串调用 search() 方法时，系统会根据默认查询选项返回结果：

  • 文档按照降序排列返回
  • 以 20 个文档为一组，每次返回一组文档
  • 检索到的文档包含其所有原有字段

您可以使用 Query 类的实例作为 search() 的参数来更改这些选项。

通过 Query 类可指定每次返回多少个文档，还可以自定义所检索文档的内容。您可以只检索文档标识符，或要求文档只包含其一部分字段。您还可以在检索的文档中创建自定义字段：片段（显示匹配字符串周围部分文本的文本字段片段）和字段表达式（具有从文档中其他字段派生的值的字段）。

除了查询选项之外，Query 类还可以包含 SortOptions 类的实例。使用排序选项，您可以更改排序顺序，并根据多个键对结果排序。

使用 Query 类进行搜索

使用 Query 类的实例进行搜索时，您需要通过几个步骤来构造该类的实例。以下是一般顺序：

  1. 创建查询字符串。
  2. 如果需要，请创建 SortOptions。
  3. 创建 QueryOptions。
  4. 创建一个包含查询字符串和（可选）QueryOptions 的 Query 对象。
  5. 在 Query 对象上调用搜索方法。

QueryOptions 和 SortOptions 构造函数使用命名参数，如以下示例所示：

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

这些属性 (Property) 控制返回的结果数和顺序。互斥的 offset 和 cursor 选项支持分页，这两个选项指定要在结果中返回哪些选定的文档。

属性 说明 默认 上限
limit 结果中可以返回的最大文档数。 20 1000
number_found_accuracy 此属性用于确定 SearchResults.number_found() 返回的结果的准确性。它设置了实际计算的匹配数的上限，达到数量上限后停止搜索。

如果索引中的匹配数小于或等于上限，则返回的计数是准确的。否则，该计数是根据找到的匹配数以及索引的大小和结构所得出的估算值。请注意，为此属性设置较高的值可能会影响搜索操作的复杂性，并可能导致超时。		 如果未指定或设置为 None，则准确性将设置为与 limit 相同的值 25000
offset 需要返回的结果的第一个文档的偏移量。 0。结果将包含所有匹配的文档（不超过上限）。 1000
cursor 可以用于代替偏移量以按排序顺序检索文档组的游标。游标在传入和传出连续查询时会进行更新，因此可使每项新搜索在前一项搜索结束处继续。处理结果页面介绍了游标和偏移量。 Null。结果将包含所有匹配的文档（不超过上限）。 -
sort_options 设置 SortOptions 对象以控制搜索结果的排序。SortOptions 实例有自己的一组属性，将在下文中进行介绍。 Null。按递减顺序对文档进行排序。 -

这些属性控制在结果中显示的文档字段。

属性 说明 默认
ids_only 设置为 True 或 False。如果为 True，则结果中返回的文档仅包含 ID，不包含任何字段。 False（返回所有字段）。
returned_fields 指定要包含在结果中的文档字段。可以指定的字段上限为 100 个。 返回所有文档字段（最多 100个字段）。
returned_expressions 字段表达式，描述要向搜索结果中所返回的每个文档添加的计算字段。这些字段会添加到文档的 expressions 属性中。请编写表达式（可包含一个或多个文档字段）来指定字段值。 无
snippeted_fields 文本字段名称列表。为每个字段生成一个片段。这是一个计算字段，它会添加到搜索结果中文档的 expressions 属性中。片段字段与其源字段具有相同的名称。

此选项仅使用两个参数隐式调用 snippet 函数，根据搜索用来检索结果的相同查询字符串创建最多具有一个匹配字符串的片段：snippet("query-string", field-name)。

要创建自定义片段，您还可以使用 returned_expressions 选项添加明确调用 snippet 函数的字段表达式。		 无

SortOptions

SortOptions 的属性用于控制搜索结果的排序和评分。

属性 说明 默认
expressions 表示文档多维排序方式的 SortExpressions 列表。 无
match_scorer 可选的 MatchScorer 对象。如果存在此对象，将根据搜索字词频率对文档进行评分。分数将在 _score 字段中提供。对文档进行评分的操作可能代价高昂（在计费操作和执行时间方面），并且可能会降低搜索速度。请谨慎使用评分。 无
limit 需要评分和/或排序的最大对象数。最大值为 10,000。 1000

根据多个键进行排序

您可以根据多个排序键对搜索结果进行排序。每个键可以是简单的字段名称，也可以是根据多个字段计算得出的值。请注意，在排序选项语境下，术语“表达式”有多种含义：SortOption 本身有一个 expressions 特性 (Attribute)。此特性是与排序键对应的一组 SortExpression 对象。最后，每个 SortExpression 对象都包含一个指定如何计算排序键的值的 expression 特性。此表达式根据下一部分中的规则进行构建。

SortExpression 还定义排序的方向以及在无法为文档计算表达式时使用的默认键值。以下是完整的属性列表：

属性 说明 默认
expression 对每个匹配文档的结果进行排序时要进行求值的表达式。 无
direction 搜索结果的排序方向：ASCENDING 或 DESCENDING。 DESCENDING
default_value 表达式的默认值（在没有字段且无法为文档计算字段时使用）。对于文本排序，必须指定文本值。必须为数字排序指定数值。 无

对多值字段进行排序

根据某特定类型的一个多值字段排序时，系统只会使用分配给该字段的第一个值。例如，假设 DocA 和 DocB 两个文档都有一个名为“color”的文本字段。赋予 DocA“color”字段的两个值依次为 (red, blue)，赋予 DocB“color”字段的两个值依次为 (green, red)。当您指定根据“color”文本字段排序时，DocA 会按值“red”排序，DocB 会按值“green”排序。此排序不使用其他字段值。

排序或不排序

如果您未指定任何排序选项，则会自动按降序返回搜索结果。在这种情况下，返回的文档没有数量限制。如果您指定了任何排序选项，则会在选择所有匹配文档后执行排序。显式属性 SortOptions.limit 控制排序文档的数量。排序文档的数量不能超过 10000，默认值为 1000。如果匹配文档多于 SortOptions.limit 指定的数量，则搜索仅检索指定数量的文档，将其排序后返回。此操作从所有匹配文档的列表（降序）中选择要排序的文档。查询选择的匹配文档可能多于您可以排序的文档数量。如果您要使用查询选项且需要检索每个匹配文档，您应确保查询返回的文档数不超过您可以排序的文档数。

编写表达式

表达式用于定义字段表达式（在“QueryOptions”中设置）和排序表达式（在 SortOptions 中设置）。它们编写为以下字符串：

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

涉及数值字段的表达式可以使用算术运算符（+、-、*、/）和下方列出的内置数值函数。涉及地理坐标点字段的表达式可以使用 geopoint 函数和 distance 函数。用于文本和 HTML 字段的表达式可以使用 snippet 函数。

表达式还可以包含以下特殊术语：

术语 说明
_rank 文档的排序属性。可用于字段表达式和排序表达式。
_score 在 SortOptions 中加入 MatchScorer 时为文档分配的分数。此术语只能出现在排序表达式中，而不适用于字段表达式。

数值函数

用于定义 FieldExpressions 和 SortExpressions 值的表达式可以使用这些内置函数。其参数必须是数字、字段名称或使用数字和字段名称的表达式。

函数 说明 示例
max 返回参数中的最大值。 max(recommended_retail_price, discount_price, wholesale_price)
min 返回参数中的最小值。 min(height, width, length)
log 返回自然对数。 log(x)
abs 返回绝对值。 abs(x)
pow 具有两个数字参数。调用 pow(x, y) 会计算 x 的 y 次幂的值。 pow(x, 2)
count 使用一个字段名称作为其参数。返回文档中具有该名称的字段数。请记住，文档可以包含多个同名但类型不同的字段。注意：count 只能在 FieldExpressions 中使用。它无法在 SortExpressions 中显示。 count(user)

地理坐标点函数

以下函数可用于涉及地理坐标点字段的表达式。

函数 说明 示例
geopoint 指定具有明确经度和纬度的地理坐标点。 geopoint(-31.3, 151.4)
distance 计算两个地理坐标点之间的距离。请注意，两个参数中的任何一个都可以是地理坐标点字段的名称或对地理坐标点函数的调用。但是，只有一个参数可以是字段名称。 distance(geopoint(23, 134), store_location)

代码段

片段是与查询字符串匹配并包含周围文本的文本字段片段。您可调用 snippet 函数来创建片段：

snippet(query, body, [max_chars])

query
带引号的查询字符串，指定要在字段中查找的文本。
body
文本、HTML 或 atom 字段的名称。
max_chars
片段中要返回的最大字符数。这是可选参数，默认为 160 个字符。

该函数返回一个 HTML 字符串。该字符串包含 body 字段值的片段，其中与查询匹配的文本以粗体显示。