企业官网建设流程全解析

Whoosh分面搜索完全教程：让用户像逛电商一样筛选结果

【免费下载链接】whooshPure-Python full-text search library项目地址: https://gitcode.com/gh_mirrors/who/whoosh

Whoosh分面搜索是 Python 全文搜索引擎 Whoosh 最实用、最强大的功能之一。Whoosh 是一个纯 Python 实现的开源全文搜索库，无需编译、无需任何二进制依赖，就能为你的网站或应用提供索引、检索、排序与分组统计能力。本文将以电商网站“品牌 + 价格区间 + 日期”的经典筛选场景为主线，带你从零掌握 Whoosh 分面搜索的排序与分组用法，让你的搜索结果页像京东、淘宝一样可筛选、可钻取。

什么是 Whoosh 分面搜索？为什么电商都用它

分面搜索（Faceted Search）的本质，是把搜索结果动态分组到多个分类维度中。比如用户搜索“手机”，侧边栏会同时出现：

用户点击任意一个分组，就能只看自己关心的那一小撮结果。Whoosh 把这种能力封装为Facet（分面）概念：每个 facet 为结果中的每篇文档关联一个“键值”，用这些键可以排序（sortedby），也可以分组（groupedby）。相关概念与全部 facet 类型都定义在 sorting.py 中，官方文档可参考docs/source/facets.rst。

Whoosh 快速入门：安装并创建可分面字段

首先安装 Whoosh：

pip install Whoosh

分面搜索的前提是让字段可排序。创建 schema 时，只需给字段加上sortable=True：

from whoosh import fields, index schema = fields.Schema( name=fields.TEXT(stored=True), brand=fields.KEYWORD(sortable=True), # 品牌：用于分组 price=fields.NUMERIC(sortable=True), # 价格：用于区间分组 pub_date=fields.DATETIME(sortable=True), # 日期：用于时间区间 ) ix = index.create_in("shop_index", schema)

💡 提示：sortable=True会让 Whoosh 为字段建立独立的“列式存储”（column），按字段排序、分组时直接读列数据，速度远快于临时加载全部词项。若你的索引是旧版本建好的，也可以用whoosh.sorting.add_sortable()为已有字段补加排序能力。

Whoosh 排序搜索结果：用 sortedby 按价格和时间排序

默认情况下 Whoosh 按相关度评分排序。想按其他字段排序，只需在Searcher.search()中传入sortedby：

with ix.searcher() as s: q = qparser.QueryParser("name", ix.schema).parse("手机") # 价格从低到高 results = s.search(q, sortedby="price") # 价格从高到低 results = s.search(q, sortedby="price", reverse=True)

search()方法的完整参数（sortedby、groupedby、maptype等）定义在 searching.py 的Searcher.search中。

多级排序：先分类、再比价

电商列表页常要求“同品牌内按价格排序”，这就要用到多级排序。可以把多个 facet 组装成列表，或手动构建MultiFacet：

from whoosh import sorting # 方式一：列表快捷方式 results = s.search(q, sortedby=["brand", "price"]) # 方式二：MultiFacet 支持单独控制每级方向 mf = sorting.MultiFacet() mf.add_field("brand") mf.add_field("price", reverse=True) # 品牌内价格从高到低 results = s.search(q, sortedby=mf)

Whoosh 分组统计结果：用 groupedby 实现电商侧边栏

分组是分面搜索的核心。把groupedby传给search()，Whoosh 会一次性算好每个分组的文档集合，然后你用results.groups()读取：

facets = sorting.Facets() facets.add_field("brand") # 按品牌分组 results = s.search(q, groupedby=facets, limit=100) groups = results.groups("brand") # {"华为": [3, 7, 12], "小米": [1, 5, 9], "苹果": [2, 8]}

只想要每组数量时，用maptype=sorting.Count更快更省内存：

results = s.search(q, groupedby="brand", maptype=sorting.Count) print(results.groups("brand")) # {"华为": 12, "小米": 8, "苹果": 6}

价格区间与日期区间分面：RangeFacet 与 DateRangeFacet

价格区间是电商侧边栏最经典的分面。RangeFacet专门为数值字段服务，一行代码划分出“0–100、100–200…”的桶：

# 字段名、区间起点、区间终点、桶宽 price_facet = sorting.RangeFacet("price", 0, 10000, 100) results = s.search(q, groupedby={"price": price_facet}) # 返回 {"0-100": 3, "100-200": 10, ...} print(results.groups("price"))

日期同理，用DateRangeFacet按年份分桶：

from datetime import datetime, timedelta date_facet = sorting.DateRangeFacet( "pub_date", datetime(2020, 1, 1), datetime(2025, 12, 31), timedelta(days=365), ) results = s.search(q, groupedby={"year": date_facet})

📌 注意：所有区间都是左闭右开（含起点、不含终点）；hardend参数可控制最后一个桶是否截断到区间末尾。

自定义查询分面：QueryFacet

想按“好评率”“是否促销”这类业务规则分组？QueryFacet允许用任意查询定义分组，比如按商品名首字母分桶：

from whoosh import query qdict = { "A–H": query.TermRange("name", "a", "h"), "I–P": query.TermRange("name", "i", "p"), "Q–Z": query.TermRange("name", "q", "z"), } qfacet = sorting.QueryFacet(qdict) results = s.search(q, groupedby={"firstltr": qfacet})

MultiFacet 多字段组合：品牌 × 价格交叉筛选

有时需要按多个字段的交叉值分组，例如同时展示“华为+低价”“华为+中价”“小米+低价”等组合。把多个字段塞进一个MultiFacet即可：

mf = sorting.MultiFacet(["brand", "price"]) results = s.search(q, groupedby={"brand/price": mf})

返回的分组键就是组合元组，适合做“多级下钻”导航。

分面性能优化：让 Whoosh 分面搜索更快

新手最容易踩的性能坑有两个：

1. allow_overlap=True慎用：默认每个文档只能归属一个分组，速度极快；一旦开启重叠分组（如一篇文档打多个 tag），Whoosh 要读取字段的全部 posting，大结果集下可能慢一个数量级。能用默认模式就别开。
2. 善用maptype：只要“每组多少个”，就用sorting.Count；只要每组最佳文档，就用sorting.Best；不需要组内排序用sorting.UnorderedList。参考实现在 sorting.py 的FacetMap一节。

另外，超大索引下可用sorting.StoredFieldFacet配合存储字段做重叠分组，避免打开海量 posting 读取器，通常比FieldFacet更快。

小结：一次搜索，排序分组全搞定

Whoosh 分面搜索的完整套路就三步：建索引时给字段加sortable=True→ 搜索时传sortedby排序、groupedby分组 → 用results.groups()渲染侧边栏。配合FieldFacet、RangeFacet、DateRangeFacet、QueryFacet、MultiFacet这五类 facet，从电商价格筛选到文档库时间过滤都能轻松实现。想要深入了解，可直接阅读仓库中的 facets.rst 官方教程，或浏览src/whoosh/sorting.py与src/whoosh/searching.py的源码注释——Whoosh 的文档字符串本身就是一份很好的进阶指南。

【免费下载链接】whooshPure-Python full-text search library项目地址: https://gitcode.com/gh_mirrors/who/whoosh