排序和分面¶

注解

whoosh 3.0中的排序和分面API发生了变化。

概述¶

whoosh中的排序和分面搜索结果基于小面. 每个方面都将一个值与搜索结果中的每个文档关联起来，允许您根据键进行排序或使用它们对文档进行分组。whoosh包括 facet types 您可以用于排序和分组（见下文）。

分选¶

默认情况下，搜索结果首先以得分最高的文档排序。你可以使用 sortedby 关键字参数，用于按其他条件（如字段值）对结果排序。

使字段可排序¶

为了对字段进行排序，应使用 sortable=True 关键字参数：

schema = fields.Schema(title=fields.TEXT(sortable=True),
                       content=fields.TEXT,
                       modified=fields.DATETIME(sortable=True)
                       )

可以在没有的字段上进行排序 sortable=True 但这需要whoosh将字段中的唯一术语加载到内存中。使用 sortable 效率更高。

关于列类型¶

创建字段时使用 sortable=True ，您告诉whoosh将该字段的每个文档值存储在柱. 列对象指定用于在磁盘上存储每个文档值的格式。

这个 whoosh.columns 模块包含几个不同的列对象实现。每个字段类型都指定一个合理的默认列类型（例如，文本字段的默认值为 whoosh.columns.VarBytesColumn ，数字字段的默认值为 whoosh.columns.NumericColumn ）但是，如果希望最大限度地提高效率，则可能需要对字段使用不同的列类型。

例如，如果字段中的所有文档值都是固定长度，则可以使用 whoosh.columns.FixedBytesColumn . 如果有一个字段，其中许多文档共享相对较少的可能值（例如“category”字段、“month”或其他枚举类型字段），则可能需要使用 whoosh.columns.RefBytesColumn （可以处理可变和固定长度值）。有用于存储每个文档位值、结构、pickled对象和压缩字节值的列类型。

若要为字段指定自定义列对象，请将其作为 sortable 关键字参数而不是 True ：：

from whoosh import columns, fields

category_col = columns.RefBytesColumn()
schema = fields.Schema(title=fields.TEXT(sortable=True),
                       category=fields.KEYWORD(sortable=category_col)

对自定义排序键使用列字段¶

添加具有可排序字段的文档时，whoosh使用您为该字段传递的值作为可排序值。例如，如果“标题”是可排序字段，则添加此文档：

writer.add_document(title="Mr. Palomar")

然后…… Mr. Palomar 作为文档的排序键存储在字段列中。

这通常很好，但有时您需要“按摩”可排序键，这样它就不同于用户在界面中搜索和/或看到的值。例如，如果允许用户按标题排序，则可能希望对可见标题和用于排序的值使用不同的值：

# Visible title
title = "The Unbearable Lightness of Being"

# Sortable title: converted to lowercase (to prevent different ordering
# depending on uppercase/lowercase), with initial article moved to the end
sort_title = "unbearable lightness of being, the"

最好的方法是使用一个额外的字段进行排序。你可以使用 whoosh.fields.COLUMN 字段类型要创建未编入索引或存储的字段，它只保留每个文档列的值：：

schema = fields.Schema(title=fields.TEXT(stored=True),
                       sort_title=fields.COLUMN(columns.VarBytesColumn())
                       )

唯一的论点 whoosh.fields.COLUMN 初始值设定项是 whoosh.columns.ColumnType 对象。您可以使用 whoosh.columns 模块。

另一个例子是，假设您正在索引与每个文档关联的自定义排序顺序的文档，例如“优先级”编号：

name=Big Wheel
price=100
priority=1

name=Toss Across
price=40
priority=3

name=Slinky
price=25
priority=2
...

可以将列字段与数字列对象一起使用，以保持“优先级”，并将其用于排序：

schema = fields.Schema(name=fields.TEXT(stored=True),
                       price=fields.NUMERIC(stored=True),
                       priority=fields.COLUMN(columns.NumericColumn("i"),
                       )

（注意 columns.NumericColumn 采用类似于python使用的代码的类型代码字符 struct 和 array 模块。

使现有字段可排序¶

如果在 sortable 在whoosh 3.0中添加了参数，或者您认为不需要字段可排序，但现在您发现需要对其排序，可以使用 whoosh.sorting.add_sortable() 效用函数：

from whoosh import columns, fields, index, sorting

# Say we have an existing index with this schema
schema = fields.Schema(title=fields.TEXT,
                       price=fields.NUMERIC)

# To use add_sortable, first open a writer for the index
ix = index.open_dir("indexdir")
with ix.writer() as w:
    # Add sortable=True to the "price" field using field terms as the
    # sortable values
    sorting.add_sortable(w, "price", sorting.FieldFacet("price"))

    # Add sortable=True to the "title" field using the
    # stored field values as the sortable value
    sorting.add_sortable(w, "title", sorting.StoredFieldFacet("title"))

调用时可以指定自定义列类型 add_sortable 使用 column 关键字参数：

add_sortable(w, "chapter", sorting.FieldFacet("chapter"),
             column=columns.RefBytesColumn())

参见文档 add_sortable() 更多信息。

排序搜索结果¶

当您告诉whoosh按字段（或字段）排序时，它使用字段列中的每个文档值作为文档的排序键。

通常，搜索结果按相关性得分降序排序。你可以通过传递 sortedby 关键字参数 search() 方法：

from whoosh import fields, index, qparser

schema = fields.Schema(title=fields.TEXT(stored=True),
                       price=fields.NUMERIC(sortable=True))
ix = index.create_in("indexdir", schema)

with ix.writer() as w:
    w.add_document(title="Big Deal", price=20)
    w.add_document(title="Mr. Big", price=10)
    w.add_document(title="Big Top", price=15)

with ix.searcher() as s:
    qp = qparser.QueryParser("big", ix.schema)
    q = qp.parse(user_query_string)

    # Sort search results from lowest to highest price
    results = s.search(q, sortedby="price")
    for hit in results:
        print(hit["title"])

您可以使用以下任何对象作为 sortedby

A FacetType 对象: 使用此对象对文档进行排序。有关可用的方面类型，请参见下文。
字段名字符串: 将字段名转换为 FieldFacet （见下文）并使用它对文档进行排序。
列表 FacetType 对象和/或字段名字符串: 将面组合成一个 MultiFacet 所以可以按多个键排序。请注意，此快捷方式不允许您反转各个方面的排序方向。要做到这一点，您需要构建 MultiFacet 反对你自己。

注解

你可以使用 reverse=True 关键字参数 Searcher.search() 方法反转整个排序方向。这比反转各个方面更有效。

实例¶

按大小字段的值排序：：

results = searcher.search(myquery, sortedby="size")

按“价格”字段的相反（最高到最低）顺序排序：

facet = sorting.FieldFacet("price", reverse=True)
results = searcher.search(myquery, sortedby=facet)

按升序大小排序，然后按降序价格排序：

mf = sorting.MultiFacet()
mf.add_field("size")
mf.add_field("price", reverse=True)
results = searcher.search(myquery, sortedby=mf)

# or...
sizes = sorting.FieldFacet("size")
prices = sorting.FieldFacet("price", reverse=True)
results = searcher.search(myquery, sortedby=[sizes, prices])

按“类别”字段排序，然后按文档分数排序：

cats = sorting.FieldFacet("category")
scores = sorting.ScoreFacet()
results = searcher.search(myquery, sortedby=[cats, scores])

访问列值¶

每个文档列的值在 Hit 对象就像存储的字段值：

schema = fields.Schema(title=fields.TEXT(stored=True),
                       price=fields.NUMERIC(sortable=True))

...

results = searcher.search(myquery)
for hit in results:
    print(hit["title"], hit["price"])

高级：如果要快速访问每个文档的属性值，可以获取列读取器对象：：

with ix.searcher() as s:
    reader = s.reader()

    colreader = s.reader().column_reader("price")
    for docnum in reader.all_doc_ids():
        print(colreader[docnum])

分组¶

向用户呈现“分面”搜索结果通常非常有用。刻面是将搜索结果动态分组为类别。类别允许用户根据感兴趣的类别查看总结果的一部分。

例如，如果您正在编程一个购物网站，您可能希望显示具有搜索结果的类别，如制造商和价格范围。

制造商	价格
苹果（5）	0美元- 100美元（2）
三洋（1）	101-500美元（10）
索尼（2）	501-1000美元（1）
东芝（5）

您可以让用户单击不同的方面值，以仅显示给定类别中的结果。

另一个有用的用户界面模式是显示，例如，不同类型的已找到文档的前5个结果，并让用户单击以查看他们感兴趣的类别的更多结果，类似于聚光灯快速结果在Mac OS X上的工作方式。

这个 `groupedby` 关键字参数¶

可以使用以下对象作为 groupedby

A FacetType 对象: 使用此对象对文档进行分组。有关可用的方面类型，请参见下文。
字段名字符串: 将字段名转换为 FieldFacet （见下文）并使用它对文档进行排序。字段的名称用作方面名称。
字段名字符串的列表或元组: 设置多个字段分组条件。
将方面名称映射到的字典 FacetType 物体: 设置多个分组条件。
A Facets 对象: 这个对象很像使用字典，但是有一些方便的方法可以使设置多个分组变得更容易。

实例¶

按“类别”字段的值分组：

results = searcher.search(myquery, groupedby="category")

按“类别”字段的值以及“标记”字段的值和日期范围分组：

cats = sorting.FieldFacet("category")
tags = sorting.FieldFacet("tags", allow_overlap=True)
results = searcher.search(myquery, groupedby={"category": cats, "tags": tags})

# ...or, using a Facets object has a little less duplication
facets = sorting.Facets()
facets.add_field("category")
facets.add_field("tags", allow_overlap=True)
results = searcher.search(myquery, groupedby=facets)

按 , 使用A MultiFacet 对象（见下文）。例如，如果有两个字段名为 tag 和 size tag 和 size 字段，如 ('tag1', 'small') ， ('tag2', 'small') ， ('tag1', 'medium') 等等：

# Generate a grouping from the combination of the "tag" and "size" fields
mf = MultiFacet(["tag", "size"])
results = searcher.search(myquery, groupedby={"tag/size": mf})

获取分面组¶

这个 Results.groups("facetname") 文档ID: ：

myfacets = sorting.Facets().add_field("size").add_field("tag")
results = mysearcher.search(myquery, groupedby=myfacets)
results.groups("size")
# {"small": [8, 5, 1, 2, 4], "medium": [3, 0, 6], "large": [7, 9]}

Results.groups()

results = mysearcher.search(myquery, groupedby=myfunctionfacet)
results.groups()

groups() Searcher 对象的 stored_fields() 方法获取文档编号并将文档的存储字段作为字典返回：

for category_name in categories:
    print "Top 5 documents in the %s category" % category_name
    doclist = categories[category_name]
    for docnum, score in doclist[:5]:
        print "  ", searcher.stored_fields(docnum)
    if len(doclist) > 5:
        print "  (%s more)" % (len(doclist) - 5)

如果需要有关组的不同信息，例如，只需要每个组中文档的计数，或者不需要对组进行排序，则可以指定 whoosh.sorting.FacetMap 类型或实例 maptype 创建时的关键字参数 FacetType ：：

# This is the same as the default
myfacet = FieldFacet("size", maptype=sorting.OrderedList)
results = mysearcher.search(myquery, groupedby=myfacet)
results.groups()
# {"small": [8, 5, 1, 2, 4], "medium": [3, 0, 6], "large": [7, 9]}

# Don't sort the groups to match the order of documents in the results
# (faster)
myfacet = FieldFacet("size", maptype=sorting.UnorderedList)
results = mysearcher.search(myquery, groupedby=myfacet)
results.groups()
# {"small": [1, 2, 4, 5, 8], "medium": [0, 3, 6], "large": [7, 9]}

# Only count the documents in each group
myfacet = FieldFacet("size", maptype=sorting.Count)
results = mysearcher.search(myquery, groupedby=myfacet)
results.groups()
# {"small": 5, "medium": 3, "large": 2}

# Only remember the "best" document in each group
myfacet = FieldFacet("size", maptype=sorting.Best)
results = mysearcher.search(myquery, groupedby=myfacet)
results.groups()
# {"small": 8, "medium": 3, "large": 7}

或者，可以指定 maptype 论证中 Searcher.search() 应用于所有方面的方法调用：

results = mysearcher.search(myquery, groupedby=["size", "tag"],
                            maptype=sorting.Count)

（您可以覆盖整个 maptype 通过指定 maptype 为他们辩护。）

刻面类型¶

FieldFacet¶

这是最常见的方面类型。它根据每个文档中某个字段中的值对或分组。如果每个文档在字段中只有一个术语（例如ID字段），则此方法通常最有效（或根本有效）：：

# Sort search results by the value of the "path" field
facet = sorting.FieldFacet("path")
results = searcher.search(myquery, sortedby=facet)

# Group search results by the value of the "parent" field
facet = sorting.FieldFacet("parent")
results = searcher.search(myquery, groupedby=facet)
parent_groups = results.groups("parent")

默认情况下， FieldFacet 仅支持 non-overlapping 分组，如果一个文档不能同时属于多个方面（每个文档将被任意排序为一个类别）。若要获取具有多值字段的重叠组，请使用 allow_overlap=True 关键字参数：

facet = sorting.FieldFacet(fieldname, allow_overlap=True)

这支持重叠的组成员身份，其中文档在一个字段中有多个术语（例如关键字字段）。如果不需要重叠，请不要使用 allow_overlap 因为它是 much 更慢，使用更多内存（请参见 allow_overlap 下面）。

QueryFacet¶

您可以设置由任意查询定义的类别。例如，可以使用前缀查询对名称进行分组：：

# Use queries to define each category
# (Here I'll assume "price" is a NUMERIC field, so I'll use
# NumericRange)
qdict = {}
qdict["A-D"] = query.TermRange("name", "a", "d")
qdict["E-H"] = query.TermRange("name", "e", "h")
qdict["I-L"] = query.TermRange("name", "i", "l")
# ...

qfacet = sorting.QueryFacet(qdict)
r = searcher.search(myquery, groupedby={"firstltr": qfacet})

默认情况下， QueryFacet 仅支持 non-overlapping 分组，其中一个文档不能同时属于多个方面（每个文档将被任意分类为一个类别）。要获取具有多值字段的重叠组，请使用 allow_overlap=True 关键字参数：

facet = sorting.QueryFacet(querydict, allow_overlap=True)

RangeFacet¶

这个 RangeFacet 用于数字字段类型。它将一系列可能的值分为若干组。例如，将基于价格的文档分组为100美元宽的存储桶：

pricefacet = sorting.RangeFacet("price", 0, 1000, 100)

第一个参数是字段的名称。接下来的两个参数是要划分的完整范围。超出此范围的值（在本例中，小于0且大于1000的值）将被排序为“缺少”（无）组。第四个参数是“间隙大小”，即范围内划分的大小。

“间隙”可以是一个列表，而不是单个值。在这种情况下，列表中的值将用于设置初始分区的大小，列表中的最后一个值是所有后续分区的大小。例如：：

pricefacet = sorting.RangeFacet("price", 0, 1000, [5, 10, 35, 50])

…将设置0-5、5-15、15-50、50-100的分区，然后使用50作为所有后续分区（即100-150、150-200等）的大小。

这个 hardend 关键字参数控制最后一个除法是钳制到范围的末尾，还是允许越过范围的末尾。例如，这个：

facet = sorting.RangeFacet("num", 0, 10, 4, hardend=False)

…给出0-4、4-8和8-12分区，而：

facet = sorting.RangeFacet("num", 0, 10, 4, hardend=True)

…给出0-4、4-8和8-10分区。（默认为 hardend=False ）

注解

范围/桶总是 inclusive 在开始和 exclusive 最后。

DateRangeFacet¶

这就像 RangeFacet 但对于日期时间字段。开始值和结束值必须为 datetime.datetime 对象和间隙为 datetime.timedelta 物体。

例如：：

from datetime import datetime, timedelta

start = datetime(2000, 1, 1)
end = datetime.now()
gap = timedelta(days=365)
bdayfacet = sorting.DateRangeFacet("birthday", start, end, gap)

和一样 RangeFacet ，可以使用间隙列表和 hardend 关键字参数。

ScoreFacet¶

这个方面有时对排序有用。

例如，要按“类别”字段排序，然后对于具有相同类别的文档，按文档的分数排序：

cats = sorting.FieldFacet("category")
scores = sorting.ScoreFacet()
results = searcher.search(myquery, sortedby=[cats, scores])

这个 ScoreFacet 总是先高分后低分。

注解

使用时 sortedby=ScoreFacet() 应给出与使用默认评分排序相同的结果（ sortedby=None ，使用方面会变慢，因为whoosh在排序时会自动关闭许多优化。

FunctionFacet¶

这个方面允许您传递一个自定义函数来计算文档的排序/分组键。（使用此方面类型可能比将方面类型和分类程序子类化以设置某些自定义行为更容易。）

将使用索引搜索器和索引文档ID作为参数调用函数。例如，如果索引中包含术语向量：

schema = fields.Schema(id=fields.STORED,
                       text=fields.TEXT(stored=True, vector=True))
ix = RamStorage().create_index(schema)

…您可以使用一个函数对文档进行排序，使其越接近两个术语的相等出现：

def fn(searcher, docnum):
    v = dict(searcher.vector_as("frequency", docnum, "text"))
    # Sort documents that have equal number of "alfa" and "bravo" first
    return 0 - (1.0 / (abs(v.get("alfa", 0) - v.get("bravo", 0)) + 1.0))

facet = sorting.FunctionFacet(fn)
results = searcher.search(myquery, sortedby=facet)

StoredFieldFacet¶

这个方面允许您使用存储的字段值作为文档的排序/分组键。这通常比使用索引字段慢，但当使用 allow_overlap 实际上，对于大型索引来说，它可以更快，因为它避免了读取发布列表的开销。

StoredFieldFacet 支架 allow_overlap 通过将存储的值拆分为单独的键。默认情况下，它调用值的 split() 方法（因为大多数存储值都是字符串），但可以提供自定义的拆分函数。请参见 allow_overlap 下面。

MultiFacet¶

此方面类型返回由两个或多个子方面返回的键的组合，允许您按多个方面的相交值排序/分组。

MultiFacet 具有用于添加方面的方法：：

myfacet = sorting.RangeFacet(0, 1000, 10)

mf = sorting.MultiFacet()
mf.add_field("category")
mf.add_field("price", reverse=True)
mf.add_facet(myfacet)
mf.add_score()

还可以传递字段名列表和/或 FacetType 初始值设定项的对象：：

prices = sorting.FieldFacet("price", reverse=True)
scores = sorting.ScoreFacet()
mf = sorting.MultiFacet(["category", prices, myfacet, scores])

遗漏值¶

排序时，对于不同方面类型，没有给定字段中任何术语的文档或其他构成“缺少”的内容的文档将始终排序到末尾。
分组时，“丢失”文档将显示在一个带有键的组中。 None .

使用重叠组¶

用于分组和排序的通用支持工作流是给定字段的一个文档值, 例如A path 包含原始文档的文件路径的字段。默认情况下，面被设置为支持这种单值方法。

当然，在某些情况下，您希望基于每个文档具有多个术语的字段将文档分为多个组。最常见的例子是 tags 字段。这个 allow_overlap 关键字参数 FieldFacet ， QueryFacet 和 StoredFieldFacet 允许这种多值方法。

但是，有一个重要的警告：使用 allow_overlap=True 比默认值慢，可能 much 对于非常大的结果集，速度较慢。这是因为whoosh必须阅读字段中每个术语的每篇文章，以创建一个临时的“转发索引”，将文档映射到术语。

如果字段被索引为项向量, FieldFacet 会用它们加速 allow_overlap 对于较小的结果集，但是对于较大的结果集，whoosh必须为每个匹配的文档打开向量列表，这仍然非常缓慢。

对于非常大的索引和结果集，如果存储了字段，则可以使用 StoredFieldFacet 而不是 FieldFacet . 虽然读取存储值通常比使用索引慢，但在这种情况下，避免打开大量的发帖阅读器的开销可以使其值得。

StoredFieldFacet 支架 allow_overlap 通过加载给定字段的存储值并将其拆分为多个值。默认值是调用值的 split() 方法。

例如，如果您存储了 tags 字段作为字符串 "tag1 tag2 tag3" ：：

schema = fields.Schema(name=fields.TEXT(stored=True),
                       tags=fields.KEYWORD(stored=True))
ix = index.create_in("indexdir")
with ix.writer() as w:
    w.add_document(name="A Midsummer Night's Dream", tags="comedy fairies")
    w.add_document(name="Hamlet", tags="tragedy denmark")
    # etc.

…然后您可以使用 StoredFieldFacet 这样地：：

ix = index.open_dir("indexdir")
with ix.searcher() as s:
    sff = sorting.StoredFieldFacet("tags", allow_overlap=True)
    results = s.search(myquery, groupedby={"tags": sff})

对于字符串以外的存储python对象，可以提供一个split函数（使用 split_fn 关键字参数 StoredFieldFacet ）函数应接受单个参数（存储值），并返回分组键的列表或元组。

使用自定义排序顺序¶

每次搜索都有一个自定义的排序顺序有时很有用。例如，不同的语言使用不同的排序顺序。如果您有返回给定字段值所需排序顺序的函数，例如Unicode排序算法（UCA）的实现，则可以自定义用户语言的排序顺序。

这个 whoosh.sorting.TranslateFacet lets you apply a function to the value of another facet. 这允许您将字段值“转换”为任意排序键，例如使用UCA:：

from pyuca import Collator

# The Collator object has a sort_key() method which takes a unicode
# string and returns a sort key
c = Collator("allkeys.txt")

# Make a facet object for the field you want to sort on
nf = sorting.FieldFacet("name")

# Wrap the facet in a TranslateFacet with the translation function
# (the Collator object's sort_key method)
tf = sorting.TranslateFacet(facet, c.sort_key)

# Use the facet to sort the search results
results = searcher.search(myquery, sortedby=tf)

（您可以将多个“包裹”面传递给 TranslateFacet ，它将使用方面的值作为多个参数调用函数。）

translatefacet还可以非常有用，用于对某些公式的输出进行排序：

# Sort based on the average of two numeric fields
def average(a, b):
    return (a + b) / 2.0

# Create two facets for the fields and pass them with the function to
# TranslateFacet
af = sorting.FieldFacet("age")
wf = sorting.FieldFacet("weight")
facet = sorting.TranslateFacet(average, af, wf)

results = searcher.search(myquery. sortedby=facet)

请记住，您仍然可以按多个方面进行排序。例如，可以先按量化函数转换的数值排序，然后按另一个字段的值排序，如果相等：

# Sort by a quantized size first, then by name
tf = sorting.TranslateFacet(quantize, sorting.FieldFacet("size"))
results = searcher.search(myquery, sortedby=[tf, "name"])

排序和分面¶

概述¶

分选¶

使字段可排序¶

关于列类型¶

对自定义排序键使用列字段¶

使现有字段可排序¶

排序搜索结果¶

实例¶

访问列值¶

分组¶

这个 `groupedby` 关键字参数¶

实例¶

获取分面组¶

刻面类型¶

FieldFacet¶

QueryFacet¶

RangeFacet¶

DateRangeFacet¶

ScoreFacet¶

FunctionFacet¶

StoredFieldFacet¶

MultiFacet¶

遗漏值¶

使用重叠组¶

使用自定义排序顺序¶

专家：写你自己的方面¶

目录

上一个主题

下一个主题

排序和分面¶

概述¶

分选¶

使字段可排序¶

关于列类型¶

对自定义排序键使用列字段¶

使现有字段可排序¶

排序搜索结果¶

实例¶

访问列值¶

分组¶

这个 groupedby 关键字参数¶

实例¶

获取分面组¶

刻面类型¶

FieldFacet¶

QueryFacet¶

RangeFacet¶

DateRangeFacet¶

ScoreFacet¶

FunctionFacet¶

StoredFieldFacet¶

MultiFacet¶

遗漏值¶

使用重叠组¶

使用自定义排序顺序¶

专家：写你自己的方面¶

这个 `groupedby` 关键字参数¶