collectors 模块

此模块包含“Collector”对象。收集器提供了一种从 whoosh.matching.Matcher 对象,实现排序、筛选、排序等,并生成 whoosh.searching.Results 对象。

基本收藏家包括:

TopCollector
返回按分数排序的前n个匹配结果,使用块质量优化跳过无法贡献前n个的文档块。 whoosh.searching.Searcher.search() 方法在默认情况下或在指定 limit .
UnlimitedCollector
返回按分数排序的所有匹配结果。这个 whoosh.searching.Searcher.search() 方法在指定 limit=None 或者指定的限制等于或大于搜索者中的文档数。
SortingCollector
返回按a排序的所有匹配结果 whoosh.sorting.Facet 对象。这个 whoosh.searching.Searcher.search() 当使用 sortedby 参数。

下面是一个简单的收集器的示例,它不是记住匹配的文档,而是计算匹配的数量:

class CountingCollector(Collector):
    def prepare(self, top_searcher, q, context):
        # Always call super method in prepare
        Collector.prepare(self, top_searcher, q, context)

        self.count = 0

    def collect(self, sub_docnum):
        self.count += 1

c = CountingCollector()
mysearcher.search_with_collector(myquery, c)
print(c.count)

还有几个包装收集器可以扩展或修改其他收集器的功能。方法:`whoosh.search.searcher.search`在指定各种参数时使用其中许多方法。

注意:收集器设计为不可重入或线程安全。通常,为每次搜索创建一个新的收集器是一个好主意。

基类

class whoosh.collectors.Collector

收集器的基类。

all_ids()

返回此收集器中匹配的docnum序列。(Only valid after the collector is run.)

默认实现基于docset。如果收集器不维护docset,则需要重写此方法。

collect(sub_docnum)

对每个匹配的文档调用此方法。它应该完成向结果中添加匹配文档的工作,并且应该返回一个对象,作为给定文档的“排序键”(例如文档的分数、一个方面生成的键或一个方面不生成的键)。子类必须实现此方法。

如果需要当前文档的分数,请使用 self.matcher.score() .

重写方法应添加当前文档偏移量( self.offsetsub_docnum 获取要添加到结果中的匹配文档的顶级文档编号。

参数:sub_docnum -- 当前子搜索程序中当前匹配的文档编号。你必须增加 self.offset 获取文档的顶级文档编号。
collect_matches()

此方法调用 Collector.matches() 然后针对每个匹配的文档调用 Collector.collect() . 希望在查找匹配项和将匹配项添加到集合(例如,筛选出某些文档)之间进行干预的子类可以重写此方法。

computes_count()

如果收集器自然地计算匹配文档的确切数量,则返回true。使用块优化的收集器将返回false,因为它们可能会跳过包含匹配文档的块。

注意,如果此方法返回false,您仍然可以调用 count() , but it means that method might have to do more work to calculate the number of matching documents.

count()

返回此收集器中匹配的文档总数。(Only valid after the collector is run.)

默认实现基于docset。如果收集器不维护docset,则需要重写此方法。

finish()

在搜索后调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.runtime
搜索所用的时间(秒)。
matches()

为当前子搜索中的匹配项生成一系列相对文档编号。

prepare(top_searcher, q, context)

在搜索之前调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.top_searcher
顶级搜索者。
self.q
查询对象
self.context
context.needs_current controls whether a wrapping collector requires that this collector's matcher be in a valid state at every call to collect() . 如果这是 False ,收集器可以自由使用不必保持匹配器更新的更快方法,例如 matcher.all_ids() .
参数:
remove(global_docnum)

从收集器中删除文档。不是说此方法使用的是全局文档编号,而不是 Collector.collect() 它采用一个段相对docnum。

results()

返回A Results 包含搜索结果的对象。子类必须实现此方法

set_subsearcher(subsearcher, offset)

每次收集器在新的子搜索器上启动时都会调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.subsearcher
当前子搜索者。如果顶级搜索者是原子搜索者,则与顶级搜索者相同。
self.offset
当前搜索者的文档编号偏移量。必须将此编号添加到传递给的文档编号中 Collector.collect() 获取用于结果的顶级文档编号。
self.matcher
A whoosh.matching.Matcher 对象,表示当前子搜索器中查询的匹配项。
sort_key(sub_docnum)

返回当前匹配项的排序键。这应该返回相同的值 Collector.collect() 但没有将当前文档添加到结果中的副作用。

如果收藏家已经准备好 context.needs_current=True ,此方法可以使用 self.matcher 获取信息,例如分数。否则,只应使用提供的 sub_docnum ,因为匹配器可能处于不一致的状态。

子类必须实现此方法。

class whoosh.collectors.ScoredCollector(replace=10)

用于根据文档分数对结果排序的收集器的基类。

参数:replace -- 尝试用更高效的版本替换匹配器之间的匹配数。
collect(sub_docnum)

对每个匹配的文档调用此方法。它应该完成向结果中添加匹配文档的工作,并且应该返回一个对象,作为给定文档的“排序键”(例如文档的分数、一个方面生成的键或一个方面不生成的键)。子类必须实现此方法。

如果需要当前文档的分数,请使用 self.matcher.score() .

重写方法应添加当前文档偏移量( self.offsetsub_docnum 获取要添加到结果中的匹配文档的顶级文档编号。

参数:sub_docnum -- 当前子搜索程序中当前匹配的文档编号。你必须增加 self.offset 获取文档的顶级文档编号。
matches()

为当前子搜索中的匹配项生成一系列相对文档编号。

prepare(top_searcher, q, context)

在搜索之前调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.top_searcher
顶级搜索者。
self.q
查询对象
self.context
context.needs_current controls whether a wrapping collector requires that this collector's matcher be in a valid state at every call to collect() . 如果这是 False ,收集器可以自由使用不必保持匹配器更新的更快方法,例如 matcher.all_ids() .
参数:
sort_key(sub_docnum)

返回当前匹配项的排序键。这应该返回相同的值 Collector.collect() 但没有将当前文档添加到结果中的副作用。

如果收藏家已经准备好 context.needs_current=True ,此方法可以使用 self.matcher 获取信息,例如分数。否则,只应使用提供的 sub_docnum ,因为匹配器可能处于不一致的状态。

子类必须实现此方法。

class whoosh.collectors.WrappingCollector(child)

包装其他收集器的收集器的基类。

all_ids()

返回此收集器中匹配的docnum序列。(Only valid after the collector is run.)

默认实现基于docset。如果收集器不维护docset,则需要重写此方法。

collect(sub_docnum)

对每个匹配的文档调用此方法。它应该完成向结果中添加匹配文档的工作,并且应该返回一个对象,作为给定文档的“排序键”(例如文档的分数、一个方面生成的键或一个方面不生成的键)。子类必须实现此方法。

如果需要当前文档的分数,请使用 self.matcher.score() .

重写方法应添加当前文档偏移量( self.offsetsub_docnum 获取要添加到结果中的匹配文档的顶级文档编号。

参数:sub_docnum -- 当前子搜索程序中当前匹配的文档编号。你必须增加 self.offset 获取文档的顶级文档编号。
collect_matches()

此方法调用 Collector.matches() 然后针对每个匹配的文档调用 Collector.collect() . 希望在查找匹配项和将匹配项添加到集合(例如,筛选出某些文档)之间进行干预的子类可以重写此方法。

count()

返回此收集器中匹配的文档总数。(Only valid after the collector is run.)

默认实现基于docset。如果收集器不维护docset,则需要重写此方法。

finish()

在搜索后调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.runtime
搜索所用的时间(秒)。
matches()

为当前子搜索中的匹配项生成一系列相对文档编号。

prepare(top_searcher, q, context)

在搜索之前调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.top_searcher
顶级搜索者。
self.q
查询对象
self.context
context.needs_current controls whether a wrapping collector requires that this collector's matcher be in a valid state at every call to collect() . 如果这是 False ,收集器可以自由使用不必保持匹配器更新的更快方法,例如 matcher.all_ids() .
参数:
remove(global_docnum)

从收集器中删除文档。不是说此方法使用的是全局文档编号,而不是 Collector.collect() 它采用一个段相对docnum。

results()

返回A Results 包含搜索结果的对象。子类必须实现此方法

set_subsearcher(subsearcher, offset)

每次收集器在新的子搜索器上启动时都会调用此方法。

子类可以重写它来执行设置工作,但是它们仍然应该调用超类的方法,因为它在收集器对象上设置了几个必要的属性:

self.subsearcher
当前子搜索者。如果顶级搜索者是原子搜索者,则与顶级搜索者相同。
self.offset
当前搜索者的文档编号偏移量。必须将此编号添加到传递给的文档编号中 Collector.collect() 获取用于结果的顶级文档编号。
self.matcher
A whoosh.matching.Matcher 对象,表示当前子搜索器中查询的匹配项。
sort_key(sub_docnum)

返回当前匹配项的排序键。这应该返回相同的值 Collector.collect() 但没有将当前文档添加到结果中的副作用。

如果收藏家已经准备好 context.needs_current=True ,此方法可以使用 self.matcher 获取信息,例如分数。否则,只应使用提供的 sub_docnum ,因为匹配器可能处于不一致的状态。

子类必须实现此方法。

基本收集器

class whoosh.collectors.TopCollector(limit=10, usequality=True, **kwargs)

只返回得分最高“n”的收集器。

参数:
  • limit -- 要返回的最大结果数。
  • usequality -- 是否使用块质量优化。这对于调试可能很有用。
class whoosh.collectors.UnlimitedCollector(reverse=False)

返回的收集器 all 得分结果。

class whoosh.collectors.SortingCollector(sortedby, limit=10, reverse=False)

返回按给定值排序的结果的收集器。 whoosh.sorting.Facet 对象。见 排序和分面 更多信息。

参数:
  • sortedby -- 看见 排序和分面 .
  • reverse -- 如果为真,则反转整体结果。请注意,您也可以在多方面排序键中反转各个方面。

包装纸

class whoosh.collectors.FilterCollector(child, allow=None, restrict=None)

允许和/或限制结果中某些文档编号的收集器:

uc = collectors.UnlimitedCollector()

ins = query.Term("chapter", "rendering")
outs = query.Term("status", "restricted")
fc = FilterCollector(uc, allow=ins, restrict=outs)

mysearcher.search_with_collector(myquery, fc)
print(fc.results())

如果出现以下情况,此收集器将丢弃文档:

  • 允许的集合不是“无”,并且文档编号不在集合中,或者
  • 限制集不是“无”,并且该集中包含文档编号。

(因此,如果两个集合中都有相同的文档编号,则该文档将被丢弃。)

如果您有对收集器的引用,则可以使用 FilterCollector.filtered_count 以获取收集器从结果中筛选出的匹配文档数。

参数:
  • child -- 要包装的收集器。
  • allow -- 一个包含结果中允许的文档编号的查询、结果对象或类似集合的对象,或无(表示允许所有内容)。
  • restrict -- 包含要从结果中禁止的文档编号的查询、结果对象或类似集合的对象,或“无”(表示不允许任何内容)。
class whoosh.collectors.FacetCollector(child, groupedby, maptype=None)

A collector that creates groups of documents based on whoosh.sorting.Facet 物体。见 排序和分面 更多信息。

如果指定 groupedby 中的参数 whoosh.searching.Searcher.search() 方法。你可以使用 whoosh.searching.Results.groups() 方法访问方面组。

如果您有对收集器的引用,也可以使用 FacetedCollector.facetmaps 要直接访问组,请执行以下操作:

uc = collectors.UnlimitedCollector()
fc = FacetedCollector(uc, sorting.FieldFacet("category"))
mysearcher.search_with_collector(myquery, fc)
print(fc.facetmaps)
参数:
class whoosh.collectors.CollapseCollector(child, keyfacet, limit=1, order=None)

基于方面折叠结果的收集器。也就是说,它消除了除共享相同方面键的前n个结果以外的所有结果。带有方面空键的文档永远不会被删除。

每组中的“最高”结果由结果排序(例如得分搜索中的最高分数)或可选的第二个“排序”方面确定。

如果您有对收集器的引用,可以使用 CollapseCollector.collapsed_counts 要访问基于每个键消除的文档数,请执行以下操作:

tc = TopCollector(limit=20)
cc = CollapseCollector(tc, "group", limit=3)
mysearcher.search_with_collector(myquery, cc)
print(cc.collapsed_counts)

折叠结果 更多信息。

参数:
  • child -- 要包装的收集器。
  • keyfacet -- 一 whoosh.sorting.Facet 用于崩溃。除了共享密钥的前n个文档之外,其他所有文档都将从结果中删除。
  • limit -- 为每个键保留的最大文档数。
  • order -- 可选的 whoosh.sorting.Facet 用于确定折叠时要保留的“顶部”文档。缺省值(默认值) orderfaceet=None )使用结果顺序(例如得分搜索中的最高得分)。
class whoosh.collectors.TimeLimitCollector(child, timelimit, greedy=False, use_alarm=True)

集电极 TimeLimit 如果搜索在特定秒数内未完成,则出现异常::

uc = collectors.UnlimitedCollector()
tlc = TimeLimitedCollector(uc, timelimit=5.8)
try:
    mysearcher.search_with_collector(myquery, tlc)
except collectors.TimeLimit:
    print("The search ran out of time!")

# We can still get partial results from the collector
print(tlc.results())

重要提示:在UNIX系统(定义了signal.sigalrm的系统)上,代码使用信号在达到时间限制时立即停止搜索。在Windows上,操作系统不支持此功能,因此搜索只检查每个找到的文档之间的时间,因此如果匹配器速度慢,搜索可能会超过时间限制。

参数:
  • child -- 要包装的收集器。
  • timelimit -- 允许搜索的最大时间(秒)。如果搜索时间长于此,它将引发 TimeLimit 例外。
  • greedy -- 如果 True ,收集器将在提升 TimeLimit 例外。
  • use_alarm -- 如果 True (默认),收集器将尝试使用signal.sigalrm(在UNIX上)。
class whoosh.collectors.TermsCollector(child, settype=<class 'set'>)

一种收集器,它能记住哪些术语出现在每个匹配的文档中,哪些术语出现在其中。

如果指定 terms=Truewhoosh.searching.Searcher.search() 方法。

如果您有对收集器的引用,也可以使用 TermsCollector.termslist 要直接访问术语列表,请执行以下操作:

uc = collectors.UnlimitedCollector()
tc = TermsCollector(uc)
mysearcher.search_with_collector(myquery, tc)
# tc.termdocs is a dictionary mapping (fieldname, text) tuples to
# sets of document numbers
print(tc.termdocs)
# tc.docterms is a dictionary mapping docnums to lists of
# (fieldname, text) tuples
print(tc.docterms)