快速开始

Whoosh 是一个用于索引文本然后搜索索引的一组类和函数。它允许您为您的内容开发自定义搜索引擎。 例如，如果您正在创建博客软件，您可以使用 Whoosh 添加搜索功能以允许用户搜索博客条目。

快速介绍

>>> from whoosh.index import create_in
>>> from whoosh.fields import *
>>> schema = Schema(title=TEXT(stored=True), path=ID(stored=True), content=TEXT)
>>> ix = create_in("indexdir", schema)
>>> writer = ix.writer()
>>> writer.add_document(title=u"First document", path=u"/a",
...                     content=u"This is the first document we've added!")
>>> writer.add_document(title=u"Second document", path=u"/b",
...                     content=u"The second one is even more interesting!")
>>> writer.commit()
>>> from whoosh.qparser import QueryParser
>>> with ix.searcher() as searcher:
...     query = QueryParser("content", ix.schema).parse("first")
...     results = searcher.search(query)
...     results[0]
...
{"title": u"First document", "path": u"/a"}

Index 和 Schema 对象

要开始使用 Whoosh，您需要一个索引 (Index) 对象。 第一次创建索引时，必须定义索引的模式 (Schema)。 该模式列出了索引中的字段。 字段 (Field) 是索引中每个文档的一条信息，例如它的标题或文本内容。 一个字段可以被索引（意味着它可以被搜索）和/或存储（意味着被索引的值与结果一起返回；这对于标题等字段很有用）。

该模式有两个字段，title 和 content：

from whoosh.fields import Schema, TEXT
schema = Schema(title=TEXT, content=TEXT)

创建索引 (Index) 时，您只需要创建一次模式 (Schema)。 模式被 pickled 并与索引一起存储。

创建 Schema 对象时，您使用关键字参数将字段名称映射到字段类型。 字段列表及其类型定义了您要索引的内容和可搜索的内容。 Whoosh 带有一些非常有用的预定义字段类型，您可以轻松创建自己的字段类型。

whoosh.fields.ID
这种类型只是将字段的整个值作为一个单元进行索引（并可选地存储）（也就是说，它不会将其分解为单个单词）。 这对于文件路径、URL、日期、类别等字段很有用。

whoosh.fields.STORED
该字段与文档一起存储，但未编入索引。 此字段类型未编入索引且不可搜索。 这对于要在搜索结果中向用户显示的文档信息很有用。

whoosh.fields.KEYWORD
此类型专为以空格或逗号分隔的关键字而设计。 这种类型是索引和可搜索的（并且可以选择存储）。 为了节省空间，它不支持短语搜索。

whoosh.fields.TEXT
这种类型用于正文。 它索引（并可选地存储）文本并存储术语位置以允许短语搜索。

whoosh.fields.NUMERIC
这种类型用于数字。 您可以存储整数或浮点数。

whoosh.fields.BOOLEAN
此类型用于布尔 (true/false) 值。

whoosh.fields.DATETIME
此类型用于日期时间对象。 有关详细信息，请参阅索引和解析日期/时间。

whoosh.fields.NGRAM 和 whoosh.fields.NGRAMWORDS
这些类型将字段文本或单个术语分解为 N-gram。 有关详细信息，请参阅 索引和搜索 N-gram。
（作为一种快捷方式，如果您不需要向字段类型传递任何参数，您可以只提供类名，Whoosh 将为您实例化该对象。）

import os.path
from whoosh.index import create_in

if not os.path.exists("index"):
    os.mkdir("index")
ix = create_in("index", schema)

（在低级别，这会创建一个存储对象来包含索引。Storage 存储对象表示将存储索引的介质。通常这将是 FileStorage，它将索引存储为目录中的一组文件。）

创建索引后，可以使用 open_dir 便捷函数打开它：

from whoosh.index import open_dir

ix = open_dir("index")

IndexWriter 对象

好的，我们已经有了一个 Index 对象，现在我们可以开始添加文档了。 Index 对象的 writer() 方法返回一个 IndexWriter 对象，它允许您将文档添加到索引。 IndexWriter 的 add_document(**kwargs) 方法接受关键字参数，其中字段名称映射到一个值：

writer = ix.writer()
writer.add_document(title=u"My document", content=u"This is my document!",
                    path=u"/a", tags=u"first short", icon=u"/icons/star.png")
writer.add_document(title=u"Second try", content=u"This is the second example.",
                    path=u"/b", tags=u"second short", icon=u"/icons/sheep.png")
writer.add_document(title=u"Third time's the charm", content=u"Examples are many.",
                    path=u"/c", tags=u"short", icon=u"/icons/book.png")
writer.commit()

两个重要说明：

• 您不必为每个字段都填写一个值。 Whoosh 不关心您是否遗漏了文档中的某个字段。
  索引文本字段必须传递一个 unicode 值。 存储但未索引的字段（STORED 字段类型）可以传递给任何 pickle-able 对象。
• 如果你有一个既被索引又被存储的文本字段，你可以索引一个 unicode 值，但在必要时存储一个不同的对象（通常不是，但有时这真的很有用）使用这个技巧：

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

在 IndexWriter 上调用 commit() 将添加的文档保存到索引中：

writer.commit()

有关详细信息，请参阅 如何索引文档。

一旦您的文档提交到索引，您就可以搜索它们。

Searcher对象

要开始搜索索引，我们需要一个 Searcher 对象：

searcher = ix.searcher()

您通常希望使用 with 语句打开搜索器 (Searcher)，以便在您完成搜索后自动关闭搜索器（搜索器对象代表许多打开的文件，因此如果您没有明确关闭它们并且系统也没有快速回收，你可能耗尽文件句柄）：

with ix.searcher() as searcher:
    ...

这当然等同于：

try:
    searcher = ix.searcher()
    ...
finally:
    searcher.close()

Searcher 的 search() 方法接受一个 Query 对象。 您可以直接构造查询对象或使用查询解析器来解析查询字符串。

例如，此查询将匹配在 “content” 字段中同时包含 “apple” 和 “bear” 的文档：

# 直接构造查询对象

from whoosh.query import *
myquery = And([Term("content", u"apple"), Term("content", "bear")])

要解析查询字符串，您可以使用 qparser 模块中的默认查询解析器。 QueryParser 构造函数的第一个参数是要搜索的默认字段。 这通常是 “正文” 字段。 第二个可选参数是用于理解如何解析字段的模式：

# 解析查询字符串

from whoosh.qparser import QueryParser
parser = QueryParser("content", ix.schema)
myquery = parser.parse(querystring)

一旦有了 Searcher 和查询对象，就可以使用 Searcher 的 search() 方法来运行查询并获取 Results 对象：

>>> results = searcher.search(myquery)
>>> print(len(results))
1
>>> print(results[0])
{"title": "Second try", "path": "/b", "icon": "/icons/sheep.png"}

默认的 QueryParser 实现了一种与 Lucene 非常相似的查询语言。 它允许您使用 AND 或 OR 连接术语，使用 NOT 删除术语，将术语组合成带括号的子句，执行范围、前缀和通配符查询，并指定要搜索的不同字段。 默认情况下，它将子句与 AND 连接在一起（因此默认情况下，您指定的所有术语必须在文档中才能匹配）：

>>> 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 包含用于处理搜索结果的额外功能，例如

• 按索引字段的值而不是相关性对结果进行排序。
• 在原始文档的摘录中突出显示搜索词。
• 根据找到的前几个文档扩展查询词。
• 对结果进行分页（例如“显示结果 1-20，第 1 页，共 4 页”）。

请参阅 如何搜索 以获取更多信息。