先了解基本概念和步驟：

Quick Start

???Whoosh是一個索引文本和搜索文本的類庫，他可以為你提供搜索文本的服務(wù)，比如如果你在創(chuàng)建一個博客的軟件，你可以用whoosh為它添加添加一個搜索功能以便用戶來搜索博客的入口

下面是一個簡短的例子：

>>>from whoosh.index importcreate_in

>>>from whoosh.fields import *

>>>schema = Schema(title =TEXT(stored = True),path = ID(stored=True),content=TEXT)

>>>ix =create_in("indexer",schema)（這里的“indexer”實際上是一個目錄，因此按照這個步驟來會出錯，你得先創(chuàng)建目錄，譯者注）

>>>writer = ix.writer()

>>>writer.add_document(title=u"Firstdocument",path=u"/a",

??????????????????? content = u"this isthe first document we've add!")

>>>writer.add_document(title=u"Second document", path=u"/b",

??????????????????????? ...???????????????????? content=u"The secondone is even more interesting!")

>>> writer.commit()

>>> from whoosh.qparser importQueryParser

>>> with ix.searcher() assearcher:

???query = QueryParser("content",ix.schema).parse("first")

???results = searcher.search(query)

???results[0]

{"title": u"Firstdocument", "path": u"/a"}

?

Index和Schema對象

[H1]?

在?開始使用whoosh之前，你需要一個index對象，在你第一次創(chuàng)建index對象時你必須定義一個Schema對象，Schema對象列出了 Index的所有域。一個域就是Index對象里面每個document的一個信息，比如他的題目或者他的內(nèi)容。一個域能夠被索引（就是能被搜索到）或者被存儲（就是得到索引之后的結(jié)果，這對于標題之類的索引非常有用）

下面這個schema對象有兩個域，“title”和“content”

from whoosh.fields import Schema,TEXT

schema = Schema(title=TEXT,content=TEXT)

當你創(chuàng)建index的時候你創(chuàng)建一次schema對象就夠了，schema是序列化并且和index存儲的。

當你創(chuàng)建索引對象的時候，需要用到關(guān)鍵字參數(shù)來將域名和類型建立映射關(guān)系，域的名字和類型決定了你在索引什么和什么事可搜索的。whoosh有很多非常有用的預定義域類型，你可以非常容易的創(chuàng)建他們。如下：

whoosh.fields.ID

whoosh.fileds.STROED

whoosh.fileds.KEYWORD

whoosh.fields.TEXT

whoosh。fields.NUMERIC

whoosh.fields.BOOLEAN

whoosh.fields.DATETIME

whoosh.fields.NGRAM和whoosh.fields.NGRAMWORDS

這種類型把文本分成n-grams（以后詳細介紹）

（為了簡便，你可以不給域類型傳遞任何參數(shù)，你可以僅僅給出類型名字whoosh會為你創(chuàng)造類的實例）

from whoosh.fields importSchema,STROED,ID,KEYWORD,TEXT

schema =Schema(title=TEXT(stored=True),content=TEXT,

??????????????? path=ID(stored=True),tags=KEYWORD,icon=STROED)

一旦你有了schema對象，你可以用create_in函數(shù)創(chuàng)建索引：

import os.path

from whoosh.fields import create_in

if not os.path.exists("index"):

???os.mkdir("index")

??? ix= create_in("index",schema)

(這創(chuàng)造了一個存儲對象來包含索引，存儲對象代表存儲索引的媒介，通常是文件存儲，也就是存在目錄的一系列文件)

在你創(chuàng)建索引之后，你可以通過open_dir函數(shù)方便地打開它

from whoosh.index import open_dir

ix = open_dir("index")

IndexWriter對象

好了我們有了索引對象現(xiàn)在我們可以添加文本。索引對象的writer()方法返回一個能夠讓你給索引添加文本的IndexWriter對象，IndexWriter對象的add_document(**kwargs)方法接受關(guān)鍵字參數(shù)：

writer = ix.writer()

writer.add_document(title=u"Mydocument", content=u"This is my document!",

???????????????????path=u"/a",tags=u"first short",icon=u"/icons/star.png")

writer.add_document(title=u"Secondtry", content=u"This is the second example.",?????????????????? path=u"/b",tags=u"second short", icon=u"/icons/sheep.png")

writer.add_document(title=u"Thirdtime's the charm", content=u"Examples are many."???????????????? path=u"/c",tags=u"short", icon=u"/icons/book.png")

writer.commit()

?

兩個重點：

1.你不必要把每一個域都填滿，whoosh不關(guān)系你是否漏掉某個域

2.被索引的文本域必須是unicode值，被存儲但是不被索引的域（STROED域類型）可以是任何和序列化的對象

如果你需要一個既要被索引又要被存儲的文本域，你可以索引一個unicode值但是存儲一個不同的對象（某些時候非常有用）

writer.add_document(title=u"Title tobe indexed",_stored_title=u"Stored title")

使用commit()方法讓IndexWriter對象將添加的文本保存到索引

writer.commit()

Searcher對象

?

在搜索文本之前，我們需要一個Searcher對象

searcher = ix.searcher()

推薦用with表達式來打開搜索對象以便searcher對象能夠自動關(guān)閉（searcher對象代表打開的一系列文件，如果你不顯式的關(guān)閉他們，系統(tǒng)會慢慢回收他們以至于有時候會用盡文件句柄）

with in.searcher() as searcher:

??? ...

這等價于：

try:

???searcher = ix.searcher()

???...

finally:

??? searcher.close()

Searcher對象的search方法使用一個Query對象，你可以直接構(gòu)造query對象或者用一個query parser來得到一個查詢語句

#Construct query objects directly

from whoosh.query import *

myquery =And([Term("content",u"apple"),Term("content","bear")])

用parser得到一個查詢語句，你可以使用默認的qparser模塊里面的query parser。QueryParser構(gòu)造器的第一個參數(shù)是默認的搜索域，這通常是“正文文本”域第二個可選參數(shù)是用來理解如何parse這個域的schema對象：

#Parse a query string

from whoosh.qparser import QueryParser

parser =QueryParser("content",ix.schema)

myquery = parser.parse(querystring)

一旦你有了Searcher和query對象，你就可以使用Searcher對象的search()方法進行查詢并且得到一個結(jié)果對象

>>>results =searcher.search(myquery)

>>>print len(results)

1

>>>print results[0]

{"title": "Second try","path": /b,"icon":"/icon/sheep.png"}

默認的QueryParser實現(xiàn)了一種類似于lucene的查詢語言，他允許你使用連接詞AND和OR以及排除詞NOT和組合詞together來搜索，他默認使用AND將從句連結(jié)起來（因此默認你所有的查詢詞必須都在問當中出現(xiàn)）

>>>print(parser.parse(u"render shade animate"))

And([Term("content","render"), Term("content", "shade"),Term("content", "animate")])

>>>print(parser.parse(u"render OR (title:shade keyword:animate)"))

Or([Term("content","render"), And([Term("title", "shade"),Term("keyword", "animate")])])

>>>print(parser.parse(u"rend*"))

Prefix("content","rend")

Whoosh處理結(jié)果包含額外的特征，例如：

1.按照結(jié)果索引域的值排序，而不是按照相關(guān)度

2.高亮顯示原文檔中的搜索詞

3.擴大查詢詞給予文檔中找到的少數(shù)值

4.分頁顯示（例如顯示1-20條結(jié)果，第一到第四頁的結(jié)果）

===================】================================】

?

Searcher：

class Searcher(object): 由index對象得到，接收query對象，返回res對象。

Wraps an:class:`~whoosh.reading.IndexReader` object and provides methods for searchingthe index. # 本質(zhì)上是對 index reader的封裝。

def __init__(self,reader, weighting=scoring.BM25F, closereader=True,

?????? ?fromindex=None, parent=None):

"""

:param?reader:An :class:`~whoosh.reading.IndexReader` object for

the index to search.

:param?weighting:A :class:`whoosh.scoring.Weighting` object to use to

score found documents.（評分模型傳入到searcher里面）

:param?closereader:Whether the underlying reader will be closed when

the searcher is closed.

:param?fromindex:An optional reference to the index of the underlying

reader. This is required for:meth:`Searcher.up_to_date` and :meth:`Searcher.refresh` to work.

"""

下面講解里面的函數(shù)：

------------------------------------------------------------------------------

1，?首先是入口函數(shù)def search(self, q, **kwargs):，首先調(diào)用c =self.collector(**kwargs)，對文檔進行過濾，self.search_with_collector(q,c)，再在過濾后的文檔集合c上處理查詢語句q。然后轉(zhuǎn)移到collector.prepare(self, q, context)，和collector.run()，由collector對象完成結(jié)果對象的獲取入口。Contex字典里面包含如評分函數(shù)之類的參數(shù)。

2， 里面還封裝了如讀取文檔某個field的總長度的函數(shù)，很多和q無關(guān)的但是可以讀取index的信息。如：doc_count_all，field_length，avg_field_length。如對特定文檔信息的查詢：defdocument_numbers(self,**kw): """Returns a generator of the document numbers fordocuments matching the given keyword arguments, where the keyword keys arefield names and the values are terms that must appear in the field，返回符合要求的文檔id集合。def document(self, **kw):返回符合要求的一個文檔。def idf(self, fieldname, text):計算單詞的idf，計算是通過調(diào)用idf = self.weighting.idf(self, fieldname, text)不過會緩存結(jié)果cache[term] = idf

3， 因為index在不斷的更新，所以search也需要跟新，和up_to_date和refresh函數(shù)都有關(guān)，所以會造成subsearchers，相應(yīng)的每個subsearcher都有一個offset，表示docnum的偏移量。

4， def postings(self, fieldname, text, weighting=None, qf=1):是一個對底層ixreader.postings，另外還會考慮subsearchers的因素和設(shè)置評分函數(shù)，返回Matcher或者MultiMatcher。這里接收的是text，不是query對象。具體可以看ixreader.postings函數(shù)。

Result對象：是結(jié)果對象。

Hit對象：是result里面的一條記錄。

?

Query解析：qparser解析字符串，得到query對象。或者自己直接構(gòu)建query對象。

不同的parser適應(yīng)不同的場景，不同的parser解析和生成不同的query，就像插件一樣進行添加，就可以獲取相應(yīng)的功能。

phrase和sequence是不兼容的，其它的是兼容的。

# 這個只需要whoosh.qparser.FuzzyTermPlugin()模糊匹配就可以了

queryParser.add_plugin(whoosh.qparser.FuzzyTermPlugin())

Q = '"BM25F function"'

Q = '"BM25F function"~2' #使用SequencePlugin后，他就不是phrase，而是sequence

Q = '"BM25F~2 function"~2'

# 這個需要whoosh.qparser.SequencePlugin()來處理復雜的邏輯，phrase里面還包含模糊匹配。不然只能處理簡單的phrase

queryParser.add_plugin(whoosh.qparser.FuzzyTermPlugin())? # 這個可別忘了

queryParser.remove_plugin_class(whoosh.qparser.PhrasePlugin)

queryParser.add_plugin(whoosh.qparser.SequencePlugin())? #phrase 和sequence是不兼容的，所以必須去掉前者，才能發(fā)揮sequence的復雜功能

?

Query類：query像是一個樹或者python的list，層層封裝包含。

class Term(qcore.Query):

Matches documents containing the given term(fieldname+text pair).

>>> Term("content",u"render")

Term是非常基本的query對象，只包含一個單詞，以及對應(yīng)要檢索的field。

Range包含NumericRange和TermRange，屬于模糊匹配。如：

>>> TermRange("id",u"apple", u"pear" )# to 'apple' and less than or equal to'pear'.

>>> nr =NumericRange("number", 10, 5925) # Match numbers from 10 to 5925 inthe "number" field.

下面講解里面的子類：

------------------------------------------------------------------------------

WrappingQuery用來給一個query對象綁定一個權(quán)重。

CompoundQuery用來封裝query之間的邏輯關(guān)系，如or，and，將簡單的query封裝成復雜的query。如Sequence和Ordered都繼承自CompoundQuery。

Span是一個計算單詞位置信息的類，SpanQuery是一個可以利用span信息的query類。來計算兩個單詞之間的距離是否滿足一定的窗口。

Sequence和Phrase都是基于位置信息的query，但是內(nèi)部都會

# Create the equivalent SpanNear2 queryfrom the terms

q = SpanNear2(terms, slop=self.slop,ordered=True, mindist=1)

# Get the matcher

m = q.matcher(searcher, context)

將查詢語句變成spanquery對象，得到匹配的doc，然后再進行評分。

Spanquery的規(guī)則只能應(yīng)用到match中，不能體現(xiàn)在score中。

?

Collector：收集文檔結(jié)果，并返回results對象，可以cache很多中間結(jié)果信息。

This module contains "collector"objects. Collectors provide a way to?gather"raw" results?from a :class:`whoosh.matching.Matcher` object,implement sorting, filtering, collation,etc., and produce a :class:`whoosh.searching.Results` object

下面講解里面的子類：

------------------------------------------------------------------------------

TopCollector：Returns the top N matching results sorted by score, usingblock-quality optimizations to skip blocks of documents that can't contributeto the top N。會直接排除掉不能排進前n名的文檔。

FilterCollector：A collector that lets you allow and/or restrict certain documentnumbers in the results。

TimeLimitCollector：A collector that raises a :class:`TimeLimit` exception if the searchdoes not complete within a certain number of second。

TermsCollector：A collector that remembers which terms appeared in which termsappeared in each matched document。

SortingCollector：Returns all matching results sorted by a:class:`whoosh.sorting.Facet` object。根據(jù)特定的規(guī)則對結(jié)果進行排序。

Here's an example of a simple collectorthat instead of remembering the matched documents just counts up the number ofmatches::

???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)

簡單的計數(shù)collector的例子。可以看出，matcher負責找到結(jié)果，collector負責進行排序，過濾，是對結(jié)果再處理。

Collector也會嵌套，比如普通collector作為TimeLimitCollector的self.child屬性來存在。TimeLimitCollector封裝了對普通collector的時間要求限制。

前面search講了，search會跳轉(zhuǎn)到collector的run函數(shù)上面。下面可以看到最終還是跳轉(zhuǎn)到query對象的match函數(shù)上，進而任務(wù)落到query返回的matcher身上：

???def run(self):

??????for subsearcher, offset in self.top_searcher.leaf_searchers():

?????????self.set_subsearcher(subsearcher,offset)

?????????self.collect_matches()

???def?set_subsearcher(self,subsearcher, offset):

???????self.subsearcher = subsearcher

???????self.offset = offset

???????self.matcher = self.q.matcher(subsearcher,self.context)

???def?collect_matches(self):

???????collect = self.collect

???????for sub_docnum in?self.matches():?#matches會獲取_step_through_matches中的id

? ??????????collect(sub_docnum)

def?_step_through_matches(self):

???????matcher = self.matcher

???????while matcher.is_active():

???????????yield matcher.id()

???????????matcher.next()

--------------------------------------------------------------------------

以Collector的子類ScoredCollector，以及ScoredCollector的子類TopCollector為例：

上面的分析可以看到通過yield協(xié)程技術(shù)，返回一個迭代器對象。迭代器一次返回docnum，然后調(diào)用collect來處理docnum。而collect函數(shù)首先調(diào)用matcher的score函數(shù)計算得到文檔的評分，在調(diào)用final_fn函數(shù)計算文檔的評分，最后在根據(jù)collector的不同調(diào)用_collect函數(shù)做不同的處理。如TopCollector就會根據(jù)分數(shù)score的大小是否排名前k，來覺得是否保存該文檔docnum，如果是UnlimitedCollector就會直接保存docnum。（注意：可以看到也是協(xié)程技術(shù)，所以相當于matcher每產(chǎn)生一個docnum，它就接著計算對應(yīng)文檔的score，所以可以看到函數(shù)self.matcher.score()不需要傳入任何參數(shù)，因為matcher里面還保存這它返回的docnum的上下文）。因為UnlimitedCollector和TopCollector都是ScoredCollector的子類，所以先用collect實現(xiàn)它們共有的部分，在使用_collect實現(xiàn)特例的部分，也實現(xiàn)代碼之間分離。所以任務(wù)都轉(zhuǎn)移到matcher.id如何產(chǎn)生docnum，以及matcher.score如何計算分數(shù)。接下來一段會先分析matcher是如何來的。

???def collect(self, sub_docnum):

???????global_docnum = self.offset + sub_docnum

???????score = self.matcher.score()

???????if self.final_fn:

???????????score =self.final_fn(self.top_searcher, global_docnum, score)

???????return self._collect(global_docnum, score)

???def _collect(self, global_docnum, score):

???????items = self.items

???????self.total += 1

???????if len(items) < self.limit:

?? ?????????heappush(items, (score, 0 -global_docnum))

???????????return 0 - score

???????elif score > items[0][0]:

???????????heapreplace(items, (score, 0 - global_docnum))

???????????self.minscore = items[0][0]

???????????return 0 - score

???????else:

???????????return 0

?

?

Query類：

以query的子類sequence為例：

???def?matcher(self, searcher,context=None):

???????subs = self.subqueries

???????if not subs:

???????????return matching.NullMatcher()

???????if len(subs) == 1:

???????????m = subs[0].matcher(searcher, context)

???????else:

???????????m = self._matcher(subs,searcher, context)

???????return m

def?_matcher(self,subs, searcher, context):

???????from whoosh.query.spans import SpanNear

???????context = context.set(needs_current=True)

???????m =?self._tree_matcher(subs,SpanNear.SpanNearMatcher, searcher,

?????????????????????????????? context, None,slop=self.slop,

??????????????????????????????ordered=self.ordered)

???????return m

???def?_tree_matcher(self,subs,mcls, searcher, context, q_weight_fn,**kwargs):

???????subms = [q.matcher(searcher, context)?forq in subs]

???????if len(subms) == 1:

???????????m = subms[0]

???????elif q_weight_fn is None:

???????????m =?make_binary_tree(mcls, subms, **kwargs)

???????else:

???????????w_subms = [(q_weight_fn(q), m) for q, m in zip(subs, subms)]

???????????m =?make_weighted_tree(mcls, w_subms, **kwargs)

???????# If this query had a boost, add a wrapping matcher to apply the boost

???????if self.boost != 1.0:

???????????m = matching.WrappingMatcher(m, self.boost)

???????return m

可以看到，標紅的代碼部分構(gòu)成遞歸循環(huán)，根據(jù)當前的查詢語句q和searcher和context，最終返回一個樹狀結(jié)構(gòu)的matcher。這里也可以看到query是如何被解析為一個樹狀結(jié)構(gòu)的，也可以看到WrappingMatcher是對多個matcher封裝成一個復合matcher。和collector得部分結(jié)合起來，最終進入到matcher.id()函數(shù)中去。（需要注意的是：構(gòu)建make_weighted_tree的時候是需要SpanNearMatcher的，這為實現(xiàn)查詢語句窗口提供了基礎(chǔ)）

---------------------------------------------------------------------------

當查詢語句是復合查詢語句的時候，會存在subqueries。否則調(diào)用matcher后生成單一的matcher，而不是樹狀結(jié)構(gòu)的，也就是生成樹狀結(jié)構(gòu)matchers里面的葉子節(jié)點。以query的子類Term為例：

???def matcher(self, searcher, context=None):

???????fieldname = self.fieldname

???????text = self.text

???????if fieldname not in searcher.schema:

???????????return matching.NullMatcher()

???????field = searcher.schema[fieldname]

???????try:

???????????text = field.to_bytes(text)

???????except ValueError:

???????????return matching.NullMatcher()

???????if (self.fieldname, text) in searcher.reader():

???????????if context is None:

??????????????? w = searcher.weighting

???????????else:

??????????????? w = context.weighting

???????????m =searcher.postings(self.fieldname, text, weighting=w)

???????????if self.minquality:

???????????????m.set_min_quality(self.minquality)

???????????if self.boost != 1.0:

??????????????? m = matching.WrappingMatcher(m,boost=self.boost)

???????????return m

???????else:

???????????return matching.NullMatcher()

可以看到對于包含一個term的查詢語句matcher函數(shù)，最終會調(diào)用searcher.postings來生成最終的matcher，單個matcher會轉(zhuǎn)移到searcher.posting，如前面所說，進而轉(zhuǎn)移到ixreader.postings函數(shù)。兩點注意：一個是評分函數(shù)weighting，另一個是單詞的權(quán)重boost都在這里進行設(shè)置后者傳入。

---------------------------------------------------------------------------

查看whoosh.util 中的make_binary_tree和make_weighted_tree

def make_binary_tree(fn, args, **kwargs):

???count = len(args)

???if not count:

???????raise ValueError("Called make_binary_tree with empty list")

???elif count == 1:

???????return args[0]

???half = count // 2

???return fn(make_binary_tree(fn, args[:half], **kwargs),

????????????? make_binary_tree(fn, args[half:],**kwargs), **kwargs)

內(nèi)容很簡單，就是利用fn遞歸構(gòu)建一個課樹。

def make_weighted_tree(fn, ls, **kwargs):

???"""Takes a function/class that takes two positionalarguments and a list of

???(weight, argument) tuples and returns a huffman-like weighted tree of

???results/instances.

???"""

???if not ls:

???????raise ValueError("Called make_weighted_tree with empty list")

???ls.sort()

???while len(ls) > 1:

???????a = ls.pop(0)

???????b = ls.pop(0)

???????insort(ls, (a[0] + b[0], fn(a[1], b[1])))

???return ls[0][1]

是構(gòu)建一個哈夫曼樹，那么權(quán)重調(diào)整了構(gòu)建樹方式的不同，權(quán)重應(yīng)該是為了加快計算速度的一個指標。總而言之，這一步只是對子查詢語句的返回的matchers構(gòu)建一個樹狀的matcher。然后再用fn進行封裝，也就是SpanNearMatcher，它返回一個SpanNearMatcher對象，但底層都還是需要歸結(jié)到ixreader.postings函數(shù)來生成matcher。到現(xiàn)在為止，從query的解析，傳入searcher，調(diào)用collector，最后又返回到searcher.postings，也就是查詢的過程最終都歸結(jié)于searcher.postings對ixreader.postings得封裝，也就是給定field和查詢text對索引進行查詢，返回匹配的docnum。Collector和query對象只不過是處理了查詢語句中的位置信息、單詞權(quán)重boost信息、與或非等的邏輯關(guān)系。接下來進入ixreader.postings。

?

whoosh.reading.IndexReader看名字也知道是訪問index的接口：

里面包含了很多訪問index屬性的方法，如：

all_terms(self):?# Yields (fieldname, text) tuples for every term in the index.返回所有的（域名，單詞）對。

all_doc_ids(self):# Returns an iterator of all (undeleted) document IDs in the reader.Matcher返回一個迭代器，一次產(chǎn)出所有的文檔id

frequency(self,fieldname, text):# Returns the total number ofinstances of the given term in the collection.返回text在特定fieldname里面的頻率。

field_length(self,fieldname):# Returns the total number of terms inthe given field.返回某個field的總長度。

doc_field_length(self,docnum, fieldname, default=0):# Returns the numberof terms in the given field in the given document.返回某個文檔的field的長度。

most_frequent_terms(self,fieldname, number=5, prefix=''): Returns the top'number' most frequent terms in the given field as a list of (frequency, text)tuples.返回出現(xiàn)次數(shù)最多前k個單詞。

------------------------------------------------------------------------

以IndexReader 的子類classSegmentReader(IndexReader)為例：

defpostings(self, fieldname, text, scorer=None):

???????from whoosh.matching.wrappers import FilterMatcher

???????if self.is_closed:

???????????raise ReaderClosed

???????if fieldname not in self.schema:

???????????raise TermNotFound("No? field%r" % fieldname)

???????text = self._text_to_bytes(fieldname, text)

???????format_ = self.schema[fieldname].format

???????matcher = self._terms.matcher(fieldname, text,format_, scorer=scorer)

???????deleted = frozenset(self._perdoc.deleted_docs())

??? ????if deleted:

???????????matcher = FilterMatcher(matcher, deleted, exclude=True)

???????return matcher

好吧，轉(zhuǎn)移到了_terms的matcher函數(shù)上了，從名字也可以看出，這是針對單個單詞的matcher。而_terms是self._terms= self._codec.terms_reader(self._storage, segment)的實例，self._codec= codec if codec else segment.codec()等等，先到此為止，先來看看matcher類。

?

?

Matcher類：處理posting lists。最基礎(chǔ)的第一個matcher對象由如：whoosh.filedb.filepostings.FilePostingReader給出。（Posting list應(yīng)該是一個term的倒排索引上文檔組成的鏈表）。

This module contains "matcher"classes. Matchers deal with posting lists. The most basic matcher, which readsthe list of postings for a term, will be provided by the backend implementation(for example, :class:`whoosh.filedb.filepostings.FilePostingReader`).

-------------------------------------------------------------------------

Matcher實現(xiàn)了對postinglists的封裝訪問，以Matcher的子類UnionMatcher為例，分析其中的函數(shù)：

def?replace(self, minquality=0):返回化簡版本的matcher，比如UnionMatcher執(zhí)行的是“或”的語義操作，如果其中一個子matcher失效了，那么就只剩下另一個了，這個時候?qū)⒘硪粋€返回即可。如果是IntersectionMatcher執(zhí)行的是“與”的語義操作，如果一個子matcher失效了，那么久返回一個NullMatcherClass，因為“與”操作，必須兩個matcher中都存在才可以，一個沒有了，就說明整個都沒有了。

def?id(self):

???????_id = self._id

???????if _id is not None:

???????????return _id

???????a = self.a

???????b = self.b

???????if not a.is_active():

???????????_id = b.id()

???????elif not b.is_active():

???????????_id = a.id()

???????else:

???????????_id = min(a.id(), b.id())

???????self._id = _id

???????return _id

?????? 可以看到，因為執(zhí)行的是“或”語義，返回每一個子matcher遇到的posting，按照從小到大的順序，先返回其中比較小的。

def?next(self):從當前posting移動下一個posting。因為是“或”操作，所以是移動id比較小的matcher。如果是IntersectionMatcher，那么肯定是移動到兩個matcher共有的且下一個最小的posting上去。

???def?score(self):

???????a = self.a

???????b = self.b

???????if not a.is_active():

???????????return b.score()

???????if not b.is_active():

???????????return a.score()

???????id_a = a.id()

???????id_b = b.id()

???????if id_a < id_b:

???????????return a.score()

???????elif id_b < id_a:

???????????return b.score()

???????else:

???????????return (a.score() + b.score())

?????? 可以看到返回兩個子matcher的評分的和。進一步從LeafMatcher的score如下所示，可以看到對于葉子節(jié)點的matcher，返回的是scorer的score函數(shù)，參數(shù)是當前自己matcher。

def?score(self):

???????return self.scorer.score(self)

???????也可以看出兩個子matcher在計算分數(shù)的時候是相互分開的，這個是很致命的。比如要統(tǒng)計查詢語句Q = '"BM25Ffunction"~2'在文檔中出現(xiàn)的次數(shù)來作為評分，這是不可能的，因為單詞BM25F形成LeafMatcher的實例lm1，單詞function形成LeafMatcher的實例lm2，lm1和lm2是分開計算分數(shù)的，所以只會得到BM25F在文檔中的頻率加上function在文檔中的頻率之和來作為分數(shù)，而不是BM25F function在窗口2內(nèi)的在文檔中的頻率。如文檔：“BM25F BM25F BM25F termfunction function”。正常的算出來的分數(shù)應(yīng)該是1，而whoosh算出來的分數(shù)是5。

???def spans(self):

???????if not self.a.is_active():

???????????return self.b.spans()

???????if not self.b.is_active():

? ??????????return self.a.spans()

???????id_a = self.a.id()

???????id_b = self.b.id()

???????if id_a < id_b:

???????????return self.a.spans()

???????elif id_b < id_a:

???????????return self.b.spans()

???????else:

???????????return sorted(set(self.a.spans()) | set(self.b.spans()))

???????返回span對象這個很重要，記錄位置窗口信息。以后再詳細講。

結(jié)合我們之前講的部分，可以看到，有matcher從posting中得到文檔id，并matcher調(diào)用scorer的score來計算分數(shù)，傳遞的參數(shù)是matcher自身。

?

?

Scoring：有兩中類，評分模型和評分函數(shù)類。

以BM25F評分模型為例。

class?BM25F(WeightingModel):

???def __init__(self, B=0.75, K1=1.2, **kwargs):

???????self.B = B

???????self.K1 = K1

???????self._field_B = {}

???????for k, v in iteritems(kwargs):

???????????if k.endswith("_B"):

??????????????? fieldname = k[:-2]

???????????????self._field_B[fieldname] = v

???def supports_block_quality(self):

???????return True

???def scorer(self, searcher, fieldname, text, qf=1):

???????if not searcher.schema[fieldname].scorable:

???????????return WeightScorer.for_(searcher, fieldname, text)

???????if fieldname in self._field_B:

???????????B = self._field_B[fieldname]

???????else:

???????????B = self.B

???????return BM25FScorer(searcher, fieldname, text, B, self.K1, qf=qf)

class?BM25FScorer(WeightLengthScorer):

???def __init__(self, searcher, fieldname, text, B, K1, qf=1):

???????parent = searcher.get_parent()? #Returns self if no parent

???????self.idf = parent.idf(fieldname, text)

???????self.avgfl = parent.avg_field_length(fieldname) or 1

???????self.B = B

???????self.K1 = K1

???????self.qf = qf

???????self.setup(searcher, fieldname, text)

?????? defscore(self, matcher):

???????return self._score(matcher.weight(), self.dfl(matcher.id()))

???def _score(self, weight, length):

???????s = bm25(self.idf, weight, length, self.avgfl, self.B, self.K1)

???????return s

?

現(xiàn)來看如何得到searcher，searcher=ix.searcher(weighting= BM25F ())可以看到，首先在定義searcher的時候的時候，傳入的是評分模型BM25F，這個時候可以設(shè)置B、K1等模型的自由參數(shù)。前面介紹過res= searcher.search(query,terms=True)最終都會回歸到searcher.postings函數(shù)上。如下：

???def postings(self, fieldname, text, weighting=None, qf=1):

???????weighting = weighting or self.weighting

???????globalscorer = weighting.scorer(self, fieldname,text, qf=qf)

???????if self.is_atomic():

???????????return?self.ixreader.postings(fieldname, text,scorer=globalscorer)

???????else:

???????????from whoosh.matching import MultiMatcher

???????????matchers = []

???????????docoffsets = []

???????????term = (fieldname, text)

???????????for subsearcher, offset in self.subsearchers:

??????????????? r = subsearcher.reader()

??????????????? if term in r:

????????????????????scorer= weighting.scorer(subsearcher, fieldname, text, qf=qf)

????????????????????m =r.postings(fieldname, text, scorer=scorer)

??????????????????? matchers.append(m)

????????????? ??????docoffsets.append(offset)

???????????if not matchers:

??????????????? raise TermNotFound(fieldname,text)

???????????return MultiMatcher(matchers, docoffsets, globalscorer)

可以看到，searcher.postings會調(diào)用評分對象的scorer函數(shù)，傳遞進去searcher對象、檢索的域fieldname和查詢文本text。結(jié)合BM25F類中的scorer函數(shù)，將bm25的參數(shù)以及searcher生成并返回BM25Fscorer對象。這樣就可以看到評分函數(shù)對象BM25Fscorer在評分的時候，可以接收到的信息有對index訪問的searcher對象，被檢索的域fieldname，檢索查詢單詞文本text，自由參數(shù)B和K1，還有詞頻信息qf。另外matcher對象是在調(diào)用BM25Fscorer的score函數(shù)時傳遞進去的。

總結(jié)一下：searcher是訪問索引信息的接口，可以獲取到域的長度、特定文檔域的長度、單詞的總詞頻等信息。Matcher是訪問滿足查詢語句要求的postings（即文檔）的信息的接口，可以獲取當前文檔的id，當前單詞在文檔中的span，當前單詞的權(quán)重weight。

?

?

Span：是實現(xiàn)窗口查詢語句的基礎(chǔ)，span本身就是兩個數(shù)表示一個區(qū)間。如[2,6]表示文檔第2個位置到第6個位置的跨度區(qū)間。

在需要位置信息的查詢語句中都是需要span的，比如：查詢在“text”域中，單詞“whoosh”出現(xiàn)在單詞“l(fā)ibrary”前面，而且它們之間的距離小于3。

???????from whoosh import query, spans

???????t1 = query.Term("text", "whoosh")

???????t2 = query.Term("text", "library")

???????q = spans.SpanNear2([t1, t2], slop=3, ordered=True)

slop表示窗口插槽的大小，ordered表示單詞之間是否有序，比如如果ordered=False，那么在text field中“whoosh and library”和“l(fā)ibrary and whoosh”都是合法的，都會被檢索到。

?

以Sequence類為例：

class Sequence(compound.CompoundQuery):

??? def _matcher(self, subs, searcher,context):

??????? from whoosh.query.spans import SpanNear

??????? context =context.set(needs_current=True)

??????? m =?self._tree_matcher(subs,SpanNear.SpanNearMatcher, searcher,

??????????????????????????????context, None, slop=self.slop,

??????????????????????????????ordered=self.ordered)

? ??????return m

可以看到Sequence類的構(gòu)造的樹裝matcher是SpanNear.SpanNearMatcher類的實例。接下來轉(zhuǎn)移到SpanNearMatcher類中：

??? class SpanNearMatcher(SpanWrappingMatcher):

??????? def __init__(self, a, b, slop=1,ordered=True, mindist=1):

??????????? self.a = a

??????????? self.b = b

??????????? self.slop = slop

??????????? self.ordered = ordered

??????????? self.mindist = mindist

????????????isect =binary.IntersectionMatcher(a, b)

????????????super(SpanNear.SpanNearMatcher,self).__init__(isect)

??????????????def?_find_next(self):

??????? ?????? ifnot self.is_active():

??????????? ?????? return

??????? ?????? child= self.child

??????? ?????? r= False

??????? ?????? spans= self._get_spans()

??????? ???????while child.is_active() and not spans:

??????????? ?????? r = child.next() or r

??????????? ?????? if not child.is_active():

??????????????? ?????? return True

??????????? ?????? spans = self._get_spans()

??????? ?????? self._spans= spans

??????? ?????? returnr

??? ?????? defnext(self):

??????? ?????? self.child.next()

??????? ???????self._find_next()

????????def _get_spans(self):

??????????? slop = self.slop

??????????? mindist = self.mindist

??????????? ordered = self.ordered

??????????? spans = set()

?

??????????? bspans = self.b.spans()

??????????? for aspan in self.a.spans():

??????????????? for bspan in bspans:

??????????????????? if (bspan.end <aspan.start - slop

??????????????????????? or (ordered andaspan.start > bspan.start)):

??????????????????????? # B is too far in frontof A, or B is in front of A

??????????????????????? # *at all* when orderedis True

??????????????????????? continue

??????????????????? if bspan.start >aspan.end + slop:

??????????????????????? # B is too far from A.Since spans are listed in

??????????????????????? # start position order,we know that all spans after

????????????????? ??????# this one will also be too far.

??????????????????????? break

?

??????????????????? # Check the distancebetween the spans

??????????????????? dist =aspan.distance_to(bspan)

??????????????????? if mindist <= dist <=slop:

??????????????????????? spans.add(aspan.to(bspan))

??????????? return sorted(spans)

從SpanNearMatcher的初始化函數(shù)中，可以看到，它是本質(zhì)上是對IntersectionMatcher類的一個封裝，也就是單詞之間執(zhí)行的是“與”邏輯。要求文檔同時包含所有的單詞。然后將IntersectionMatcher設(shè)置為SpanNearMatcher的child屬性（標紅的代碼部分）。也就是self.child來獲取IntersectionMatcher對象。這個可以看SpanWrappingMatcher的構(gòu)造函數(shù)。

之前的分析，我們知道每次通過調(diào)用matcher的next函數(shù)來使得matcher從當前posting移動到下一個posting。由上面的代碼可以看到（標綠的代碼部分），先要調(diào)用self.child.next()函數(shù)，進行移動，因為child是IntersectionMatcher對象，執(zhí)行的是“與”邏輯，也就是會移動下一個包含所有查詢單詞的posting上。但是接著又調(diào)用了_find_next函數(shù)。

可以看到_find_next中主體是一個while循環(huán)，循環(huán)退出的條件是spans不為空，或者child.is_active()死掉了，也就是IntersectionMatcher對象找不到下一個符合條件的posting對象了。循環(huán)的主體是調(diào)用self.child.next()移動到下一個符合條件的posting上，并獲取當前posting的spans，這個spans保存了當前posting(文檔)中符合窗口條件的所有位置，如果spans為空，說明當前posting(文檔)雖然包含了所有的查詢單詞，但是單詞的位置不滿足窗口條件。

_get_spans可以看到是如何計算spans的，計算spans的過程，也是檢查是否符合窗口條件的過程?？梢钥吹綄τ趦蓚€單詞的spans，先獲取各自在文檔中的spans，也就是在文檔中出現(xiàn)位置的，起始和結(jié)束位置對，[起點，終點]，然后依次計算a的span和b中的span之間的距離是否滿足slop距離。a和b中的span都是從小打到按照順序遍歷的。

-------------------------------------------------------------------------

到此我們可以看到，whoosh是如何找到滿足特定窗口條件查詢語句的文檔，但是span的應(yīng)用僅限于查找文檔。也就是matcher.next()和matcher.id()。當調(diào)用matcher.scorer對文檔進行評分的時候，都是按照查找樹的結(jié)構(gòu)遞歸下去，每個單詞單獨計算評分，然后再進行匯總，也就是我們之前說的，無法計算“whoosh query~2”在對文檔中出現(xiàn)的次數(shù)來作為文檔的評分。因為spans信息跟就沒有傳送到評分模型類中。

當然也不可以天真的認為match對象會傳送給Scorer類，然后通過傳遞的matcher來獲取span信息，因為傳進去的matcher是這個單詞的matcher，里面只包含了當前text在當前docnum中的spans信息，它的評分層次是基于單個單詞，沒有提供基于幾個單詞的，或者phrase或者sequence整體層次的評分接口。如果要實現(xiàn)的話，得修改SpanWrappingMatcher中的scorer函數(shù)

轉(zhuǎn)載于:https://www.cnblogs.com/kiko0o0/p/8417141.html

總結(jié)

以上是生活随笔為你收集整理的whoosh----索引|搜索文本类库的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。