writing 模块

writer

class whoosh.writing.IndexWriter

用于写入索引的高级对象。

To get a writer for a particular index, call writer() 在索引对象上。

>>> writer = myindex.writer()

可以将此对象用作上下文管理器。如果在其调用的上下文中引发异常 cancel() 清理临时文件,否则它调用 commit() 当上下文退出时。

>>> with myindex.writer() as w:
...     w.add_document(title="First document", content="Hello there.")
...     w.add_document(title="Second document", content="This is easy!")
abstract add_document(**fields)

关键字参数将字段名映射到要索引/存储的值:

w = myindex.writer()
w.add_document(path=u"/a", title=u"First doc", text=u"Hello")
w.commit()

根据字段类型,某些字段可能采用Unicode字符串以外的对象。例如,数字字段采用数字,日期时间字段采用 datetime.datetime 物体::

from datetime import datetime, timedelta
from whoosh import index
from whoosh.fields import *

schema = Schema(date=DATETIME, size=NUMERIC(float), content=TEXT)
myindex = index.create_in("indexdir", schema)

w = myindex.writer()
w.add_document(date=datetime.now(), size=5.5, content=u"Hello")
w.commit()

您可以提供对象的列表或元组,而不是单个对象(即Unicode字符串、数字或日期时间)。对于Unicode字符串,这将绕过字段的分析器。对于数字和日期,可以为给定字段添加多个值:

date1 = datetime.now()
date2 = datetime(2005, 12, 25)
date3 = datetime(1999, 1, 1)
w.add_document(date=[date1, date2, date3], size=[9.5, 10],
               content=[u"alfa", u"bravo", u"charlie"])

对于索引和存储的字段,可以使用关键字参数指定要存储的替代值,格式为“_stored_u<fieldname>”。例如,如果您有一个名为“title”的字段,并且希望为文本“a b c”编制索引,但要存储文本“e f g”,请使用如下关键字参数:

writer.add_document(title=u"a b c", _stored_title=u"e f g")

通过指定 _<fieldname>_boost 关键字参数。例如,如果有一个名为“content”的字段,则可以将此文档的权重加倍,以便在“content”字段中进行搜索,如下所示:

writer.add_document(content="a b c", _title_boost=2.0)

你可以使用 _boost 关键字。例如,要将字段“a”和“b”增加2.0,将字段“c”增加3.0,请执行以下操作:

writer.add_document(a="alfa", b="bravo", c="charlie",
                    _boost=2.0, _c_boost=3.0)

请注意,有些评分算法,包括whoosh的默认bm25f,不适用于权重小于1的术语,因此通常不应使用小于1的增强因子。

也见 Writer.update_document() .

add_field(fieldname, fieldtype, **kwargs)

将字段添加到索引的架构中。

参数
cancel()

取消此对象添加的任何文档/删除操作并解锁索引。

commit()

完成写入并解锁索引。

delete_by_query(q, searcher=None)

删除与查询对象匹配的所有文档。

返回

删除的文档数。

delete_by_term(fieldname, text, searcher=None)

删除“fieldname”字段中包含“term”的所有文档。当索引字段包含每个文档的唯一ID(如“路径名”)时,这非常有用。

返回

删除的文档数。

abstract delete_document(docnum, delete=True)

按编号删除文档。

end_group()

完成对一组分层文档的索引。见 start_group() .

group()

返回一个调用 start_group()end_group() 为了你,允许你使用 with 对分层文档分组的语句:

with myindex.writer() as w:
    with w.group():
        w.add_document(kind="class", name="Accumulator")
        w.add_document(kind="method", name="add")
        w.add_document(kind="method", name="get_result")
        w.add_document(kind="method", name="close")

    with w.group():
        w.add_document(kind="class", name="Calculator")
        w.add_document(kind="method", name="add")
        w.add_document(kind="method", name="multiply")
        w.add_document(kind="method", name="get_result")
        w.add_document(kind="method", name="close")
abstract reader(**kwargs)

返回现有索引的读取器。

remove_field(fieldname, **kwargs)

从索引架构中删除命名字段。根据后端实现的不同,这可能会或可能不会从索引中实际删除字段的现有数据。优化索引应始终清除已删除字段的现有数据。

start_group()

开始为一组分层文档编制索引。后端应该确保这些文档都添加到同一段中:

with myindex.writer() as w:
    w.start_group()
    w.add_document(kind="class", name="Accumulator")
    w.add_document(kind="method", name="add")
    w.add_document(kind="method", name="get_result")
    w.add_document(kind="method", name="close")
    w.end_group()

    w.start_group()
    w.add_document(kind="class", name="Calculator")
    w.add_document(kind="method", name="add")
    w.add_document(kind="method", name="multiply")
    w.add_document(kind="method", name="get_result")
    w.add_document(kind="method", name="close")
    w.end_group()

将文档分组的一种更方便的方法是使用 group() 方法与 with 语句。

update_document(**fields)

关键字参数将字段名映射到要索引/存储的值。

此方法将新文档添加到索引中,并自动删除架构中标记为“唯一”的任何字段中具有相同值的任何文档::

schema = fields.Schema(path=fields.ID(unique=True, stored=True),
                       content=fields.TEXT)
myindex = index.create_in("index", schema)

w = myindex.writer()
w.add_document(path=u"/", content=u"Mary had a lamb")
w.commit()

w = myindex.writer()
w.update_document(path=u"/", content=u"Mary had a little lamb")
w.commit()

assert myindex.doc_count() == 1

使用安全 update_document 代替 add_document ;如果没有要替换的现有文档,则只需添加一个。

当前不能将值列表或元组传递给“unique”字段。

由于此方法必须搜索具有相同唯一字段的文档,并在添加新文档之前将其删除,因此它比使用 add_document .

  • 在模式中将更多字段标记为“唯一”将使每个字段 update_document 稍微慢一点。

  • 当您更新多个文档时,批量删除所有更改的文档,然后使用 add_document 添加替换而不是使用 update_document .

请注意,此方法将只替换 committed 文档;当前无法替换已添加到索引编写器但尚未提交的文档。例如,如果您这样做:

>>> writer.update_document(unique_id=u"1", content=u"Replace me")
>>> writer.update_document(unique_id=u"1", content=u"Replacement")

…这将添加两个具有相同值的文档 unique_id ,而不是用第二个文档替换第一个文档。

Writer.add_document() 有关的信息 _stored_<fieldname>_<fieldname>_boost_boost 关键字参数。

实用的writers

class whoosh.writing.BufferedWriter(index, period=60, limit=10, writerargs=None, commitargs=None)

便利类,其作用类似于编写器,但在将缓冲文档作为批处理转储到实际索引之前缓冲添加的文档。

在连续快速添加单个文档的情况下(例如,许多用户同时添加内容的Web应用程序),使用BufferedWriter much 比为您添加的每个文档打开和提交一个编写器更快。如果一次添加成批的文档,则可以使用常规的编写器。

(This class may also be useful for batches of update_document 调用。在普通writer中, update_document 调用无法更新您添加的文档 在那位writer中. 用 BufferedWriter ,这将起作用。)

要使用这个类,请从索引创建它,然后 保持开放, 在线程之间共享。

>>> from whoosh.writing import BufferedWriter
>>> writer = BufferedWriter(myindex, period=120, limit=20)
>>> # Then you can use the writer to add and update documents
>>> writer.add_document(...)
>>> writer.add_document(...)
>>> writer.add_document(...)
>>> # Before the writer goes out of scope, call close() on it
>>> writer.close()

注解

此对象将文档存储在内存中,并可能使底层编写器保持打开状态,因此必须显式调用 close() 方法来释放写锁,并确保保存所有未提交的更改。

您可以通过调用 BufferedWriter.reader()BufferedWriter.searcher() . 这允许准实时搜索,在文档提交到磁盘之前,文档一旦在内存中缓冲,就可以进行搜索。

小技巧

通过使用共享编写器中的搜索者,多个 threads 可以搜索缓冲文档。当然,其他 processes 将只看到已写入磁盘的文档。如果希望索引文档尽快可供其他进程使用,则必须使用传统的编写器而不是 BufferedWriter .

你可以控制 BufferedWriter 使用 periodlimit 争论。 period 是两次提交之间的最大秒数。 limit 是提交之间向缓冲区添加的最大数目。

你不需要调用 commit()BufferedWriter 手动。这样做只需提前将缓冲文档刷新到磁盘。您可以在调用后继续进行更改 commit() ,你可以调用 commit() 多次。

参数
  • index -- 这个 whoosh.index.Index 写信给

  • period -- 提交之间的最长时间(秒)。设置为 0None 不使用计时器。不要将此设置低于几秒钟。

  • limit -- 提交前要缓冲的最大文档数。

  • writerargs -- 指定要传递到索引的关键字参数的字典 writer() 方法。

add_document(**fields)

关键字参数将字段名映射到要索引/存储的值:

w = myindex.writer()
w.add_document(path=u"/a", title=u"First doc", text=u"Hello")
w.commit()

根据字段类型,某些字段可能采用Unicode字符串以外的对象。例如,数字字段采用数字,日期时间字段采用 datetime.datetime 物体::

from datetime import datetime, timedelta
from whoosh import index
from whoosh.fields import *

schema = Schema(date=DATETIME, size=NUMERIC(float), content=TEXT)
myindex = index.create_in("indexdir", schema)

w = myindex.writer()
w.add_document(date=datetime.now(), size=5.5, content=u"Hello")
w.commit()

您可以提供对象的列表或元组,而不是单个对象(即Unicode字符串、数字或日期时间)。对于Unicode字符串,这将绕过字段的分析器。对于数字和日期,可以为给定字段添加多个值:

date1 = datetime.now()
date2 = datetime(2005, 12, 25)
date3 = datetime(1999, 1, 1)
w.add_document(date=[date1, date2, date3], size=[9.5, 10],
               content=[u"alfa", u"bravo", u"charlie"])

对于索引和存储的字段,可以使用关键字参数指定要存储的替代值,格式为“_stored_u<fieldname>”。例如,如果您有一个名为“title”的字段,并且希望为文本“a b c”编制索引,但要存储文本“e f g”,请使用如下关键字参数:

writer.add_document(title=u"a b c", _stored_title=u"e f g")

通过指定 _<fieldname>_boost 关键字参数。例如,如果有一个名为“content”的字段,则可以将此文档的权重加倍,以便在“content”字段中进行搜索,如下所示:

writer.add_document(content="a b c", _title_boost=2.0)

你可以使用 _boost 关键字。例如,要将字段“a”和“b”增加2.0,将字段“c”增加3.0,请执行以下操作:

writer.add_document(a="alfa", b="bravo", c="charlie",
                    _boost=2.0, _c_boost=3.0)

请注意,有些评分算法,包括whoosh的默认bm25f,不适用于权重小于1的术语,因此通常不应使用小于1的增强因子。

也见 Writer.update_document() .

commit(restart=True)

完成写入并解锁索引。

delete_document(docnum, delete=True)

按编号删除文档。

reader(**kwargs)

返回现有索引的读取器。

update_document(**fields)

关键字参数将字段名映射到要索引/存储的值。

此方法将新文档添加到索引中,并自动删除架构中标记为“唯一”的任何字段中具有相同值的任何文档::

schema = fields.Schema(path=fields.ID(unique=True, stored=True),
                       content=fields.TEXT)
myindex = index.create_in("index", schema)

w = myindex.writer()
w.add_document(path=u"/", content=u"Mary had a lamb")
w.commit()

w = myindex.writer()
w.update_document(path=u"/", content=u"Mary had a little lamb")
w.commit()

assert myindex.doc_count() == 1

使用安全 update_document 代替 add_document ;如果没有要替换的现有文档,则只需添加一个。

当前不能将值列表或元组传递给“unique”字段。

由于此方法必须搜索具有相同唯一字段的文档,并在添加新文档之前将其删除,因此它比使用 add_document .

  • 在模式中将更多字段标记为“唯一”将使每个字段 update_document 稍微慢一点。

  • 当您更新多个文档时,批量删除所有更改的文档,然后使用 add_document 添加替换而不是使用 update_document .

请注意,此方法将只替换 committed 文档;当前无法替换已添加到索引编写器但尚未提交的文档。例如,如果您这样做:

>>> writer.update_document(unique_id=u"1", content=u"Replace me")
>>> writer.update_document(unique_id=u"1", content=u"Replacement")

…这将添加两个具有相同值的文档 unique_id ,而不是用第二个文档替换第一个文档。

Writer.add_document() 有关的信息 _stored_<fieldname>_<fieldname>_boost_boost 关键字参数。

class whoosh.writing.AsyncWriter(index, delay=0.25, writerargs=None)

编写器对象的便利包装器,可能由于锁定而失败(即 filedb writer)此对象将尝试一次获取底层编写器,如果成功,则只将方法调用传递给它。

如果这个对象 can't 马上找个writer,他会的 buffer 删除、添加和更新内存中的方法调用,直到调用 commit() . 此时,这个对象将开始在一个单独的线程中运行,尝试一遍又一遍地获取编写器,一旦获得它,就“重放”它上面所有的缓冲方法调用。

在一个典型的场景中,作为Web事务的结果,您将向索引添加一个或几个文档,这样您就可以创建写入器、添加和提交,而不必担心索引锁、重试等。

例如,要找一个异步的writer,而不是这个:

>>> writer = myindex.writer()

这样做:

>>> from whoosh.writing import AsyncWriter
>>> writer = AsyncWriter(myindex)
参数
  • index -- 这个 whoosh.index.Index 写信给

  • delay -- 尝试实例化实际编写器之间的延迟(秒)。

  • writerargs -- 指定要传递到索引的关键字参数的可选字典 writer() 方法。

add_document(*args, **kwargs)

关键字参数将字段名映射到要索引/存储的值:

w = myindex.writer()
w.add_document(path=u"/a", title=u"First doc", text=u"Hello")
w.commit()

根据字段类型,某些字段可能采用Unicode字符串以外的对象。例如,数字字段采用数字,日期时间字段采用 datetime.datetime 物体::

from datetime import datetime, timedelta
from whoosh import index
from whoosh.fields import *

schema = Schema(date=DATETIME, size=NUMERIC(float), content=TEXT)
myindex = index.create_in("indexdir", schema)

w = myindex.writer()
w.add_document(date=datetime.now(), size=5.5, content=u"Hello")
w.commit()

您可以提供对象的列表或元组,而不是单个对象(即Unicode字符串、数字或日期时间)。对于Unicode字符串,这将绕过字段的分析器。对于数字和日期,可以为给定字段添加多个值:

date1 = datetime.now()
date2 = datetime(2005, 12, 25)
date3 = datetime(1999, 1, 1)
w.add_document(date=[date1, date2, date3], size=[9.5, 10],
               content=[u"alfa", u"bravo", u"charlie"])

对于索引和存储的字段,可以使用关键字参数指定要存储的替代值,格式为“_stored_u<fieldname>”。例如,如果您有一个名为“title”的字段,并且希望为文本“a b c”编制索引,但要存储文本“e f g”,请使用如下关键字参数:

writer.add_document(title=u"a b c", _stored_title=u"e f g")

通过指定 _<fieldname>_boost 关键字参数。例如,如果有一个名为“content”的字段,则可以将此文档的权重加倍,以便在“content”字段中进行搜索,如下所示:

writer.add_document(content="a b c", _title_boost=2.0)

你可以使用 _boost 关键字。例如,要将字段“a”和“b”增加2.0,将字段“c”增加3.0,请执行以下操作:

writer.add_document(a="alfa", b="bravo", c="charlie",
                    _boost=2.0, _c_boost=3.0)

请注意,有些评分算法,包括whoosh的默认bm25f,不适用于权重小于1的术语,因此通常不应使用小于1的增强因子。

也见 Writer.update_document() .

add_field(*args, **kwargs)

将字段添加到索引的架构中。

参数
cancel(*args, **kwargs)

取消此对象添加的任何文档/删除操作并解锁索引。

commit(*args, **kwargs)

完成写入并解锁索引。

delete_by_term(*args, **kwargs)

删除“fieldname”字段中包含“term”的所有文档。当索引字段包含每个文档的唯一ID(如“路径名”)时,这非常有用。

返回

删除的文档数。

delete_document(*args, **kwargs)

按编号删除文档。

reader()

返回现有索引的读取器。

remove_field(*args, **kwargs)

从索引架构中删除命名字段。根据后端实现的不同,这可能会或可能不会从索引中实际删除字段的现有数据。优化索引应始终清除已删除字段的现有数据。

run()

表示线程活动的方法。

可以在子类中重写此方法。标准的run()方法调用作为目标参数(如果有)传递给对象的构造函数的可调用对象,其中顺序参数和关键字参数分别取自args和kwargs参数。

update_document(*args, **kwargs)

关键字参数将字段名映射到要索引/存储的值。

此方法将新文档添加到索引中,并自动删除架构中标记为“唯一”的任何字段中具有相同值的任何文档::

schema = fields.Schema(path=fields.ID(unique=True, stored=True),
                       content=fields.TEXT)
myindex = index.create_in("index", schema)

w = myindex.writer()
w.add_document(path=u"/", content=u"Mary had a lamb")
w.commit()

w = myindex.writer()
w.update_document(path=u"/", content=u"Mary had a little lamb")
w.commit()

assert myindex.doc_count() == 1

使用安全 update_document 代替 add_document ;如果没有要替换的现有文档,则只需添加一个。

当前不能将值列表或元组传递给“unique”字段。

由于此方法必须搜索具有相同唯一字段的文档,并在添加新文档之前将其删除,因此它比使用 add_document .

  • 在模式中将更多字段标记为“唯一”将使每个字段 update_document 稍微慢一点。

  • 当您更新多个文档时,批量删除所有更改的文档,然后使用 add_document 添加替换而不是使用 update_document .

请注意,此方法将只替换 committed 文档;当前无法替换已添加到索引编写器但尚未提交的文档。例如,如果您这样做:

>>> writer.update_document(unique_id=u"1", content=u"Replace me")
>>> writer.update_document(unique_id=u"1", content=u"Replacement")

…这将添加两个具有相同值的文档 unique_id ,而不是用第二个文档替换第一个文档。

Writer.add_document() 有关的信息 _stored_<fieldname>_<fieldname>_boost_boost 关键字参数。

例外情况

exception whoosh.writing.IndexingError