SQLite 搜索是 Frappe 应用程序的一个全文搜索框架，利用 SQLite 的 FTS5（全文搜索）引擎提供高级搜索功能。它提供了拼写纠正、基于时间的时效性评分、自定义排名、权限感知过滤和可扩展的评分管道等功能。

目录

• 快速开始

• 工作原理

• 配置

• 功能与自定义

• API 参考

快速开始

1. 创建搜索类

通过继承 SQLiteSearch 来创建搜索实现：

# my_app/search.py

from frappe.search.sqlite_search import SQLiteSearch

class MyAppSearch(SQLiteSearch):

    # Database file name

    INDEX_NAME = "my_app_search.db"

    # Define the search schema

    INDEX_SCHEMA = {

        "metadata_fields": ["project", "owner", "status"],

        "tokenizer": "unicode61 remove_diacritics 2 tokenchars '-_'",

    }

    # Define which doctypes to index and their field mappings

    INDEXABLE_DOCTYPES = {

        "Task": {

            "fields": ["name", {"title": "subject"}, {"content": "description"}, "modified", "project", "owner", "status"],

        },

        "Issue": {

            "fields": ["name", "title", "description", {"modified": "last_updated"}, "project", "owner"],

            "filters": {"status": ("!=", "Closed")},  # Only index non-closed issues

        },

    }

    def get_search_filters(self):

        """Return permission filters for current user"""

        # Get projects accessible to current user

        accessible_projects = frappe.get_all(

            "Project",

            filters={"owner": frappe.session.user},

            pluck="name"

        )

        if not accessible_projects:

            return {"project": []}  # No access

        return {"project": accessible_projects}

2. 注册搜索类

将你的搜索类添加到 hooks.py 文件中：

# my_app/hooks.py

sqlite_search = ['my_app.search.MyAppSearch']

3. 创建 API 端点

创建一个白名单方法来暴露搜索功能：

# my_app/api.py

import frappe

from my_app.search import MyAppSearch

@frappe.whitelist()

def search(query, filters=None):

    search = MyAppSearch()

    result = search.search(query, filters=filters)

    return result

4. 构建索引

通过编程方式或控制台构建搜索索引：

from my_app.search import MyAppSearch

search = MyAppSearch()

search.build_index()

工作原理

1. 索引过程

完整索引构建

当你调用 build_index() 时，框架会执行一次完整的索引重建：

1. 数据库准备：创建一个临时的 SQLite 数据库，并根据你的模式配置 FTS5 表

2. 文档收集：使用配置的字段映射和过滤器查询所有指定的 DocType

3. 文档处理：对于每个文档：

   • 根据 INDEXABLE_DOCTYPES 配置提取和映射字段

   • 使用 BeautifulSoup 清理 HTML 内容以提取纯文本

   • 如果覆盖了 prepare_document()，则应用自定义的文档准备逻辑

   • 验证必填字段（标题、内容）是否存在

4. 批量插入：将处理后的文档分批插入 FTS5 索引以提高性能

5. 词汇表构建：从所有索引文本中构建拼写纠正字典

6. 原子替换：以原子方式用新数据库替换现有索引数据库

单个文档索引

使用 index_doc() 或 remove_doc() 进行实时更新：

1. 单个文档处理：使用相同的字段映射逻辑检索并处理一个文档

2. 增量更新：通过插入、更新或删除特定文档来更新现有的 FTS5 索引

3. 词汇表更新：使用文档中的新术语更新拼写字典

2. 搜索过程

当用户使用 search() 执行搜索时，框架会执行以下步骤：

1. 权限过滤：调用 get_search_filters() 来确定当前用户可以访问哪些文档

2. 查询预处理：

   • 验证搜索查询不为空

   • 将用户提供的过滤器与权限过滤器合并

3. 拼写纠正：

   • 对照词汇字典分析查询词条

   • 使用三元组相似度来为拼写错误的单词提供纠正建议

   • 使用纠正后的词条扩展原始查询

4. FTS5 查询执行：

   • 构建一个兼容 FTS5 的查询字符串

   • 对 SQLite 数据库执行全文搜索

   • 应用元数据过滤器（状态、所有者、项目等）

   • 检索带有 BM25 分数的原始结果

5. 结果处理：

   • 自定义评分：应用评分管道来计算最终的相关性分数

     • 基础 BM25 分数处理

     • 标题匹配加权（精确匹配和部分匹配）

     • 基于文档年龄的时效性加权

     • 自定义评分函数（特定 DocType、基于优先级等）

   • 排名：按最终分数对结果进行排序并分配排名位置

   • 内容格式化：生成内容摘要并高亮匹配词条

配置

INDEX_SCHEMA

定义搜索索引的结构：

INDEX_SCHEMA = {

    # Text fields that will be searchable (defaults to ["title", "content"])

    "text_fields": ["title", "content"],

    # Metadata fields stored alongside text content for filtering

    "metadata_fields": ["project", "owner", "status", "priority"],

    # FTS5 tokenizer configuration

    "tokenizer": "unicode61 remove_diacritics 2 tokenchars '-_@.'"

}

INDEXABLE_DOCTYPES

指定要索引的 DocType 以及如何映射其字段：

INDEXABLE_DOCTYPES = {

    "Task": {

        # Field mapping

        "fields": [

            "name",

            {"title": "subject"},        # Maps subject field to title

            {"content": "description"},  # Maps description field to content

            {"modified": "creation"},    # Use creation instead of modified for recency boost

            "project",

            "owner"

        ],

        # Optional filters to limit which records are indexed

        "filters": {

            "status": ("!=", "Cancelled"),

            "docstatus": ("!=", 2)

        }

    }

}

字段映射规则

• 字符串字段：直接映射 "field_name"

• 别名字段：字典映射 {"schema_field": "doctype_field"}

• 必填字段：title 和 content 字段必须存在或显式映射（例如 {"title": "subject"}）

• 自动添加的字段：doctype 和 name 会自动包含

• 修改字段：如果在任何文档类型配置中使用，则会自动添加。用于近期加权 – 如果您想使用不同的时间戳字段（如 creation 或 last_updated），请使用 {"modified": "creation"} 将其映射到 modified

功能与自定义

权限过滤

实现 get_search_filters() 来控制访问权限：

def get_search_filters(self):

    """Return filters based on user permissions"""

    user = frappe.session.user

    if user == "Administrator":

        return {}  # No restrictions

    # Example: User can only see their own and public documents

    return {

        "owner": user,

        "status": ["Active", "Published"]

    }

自定义评分

创建自定义评分函数以影响搜索相关性：

class MyAppSearch(SQLiteSearch):

    ...

    @SQLiteSearch.scoring_function

    def *get*priority_boost(self, row, query, query_words):

        """Boost high-priority items"""

        priority = row.get("priority", "Medium")

        if priority == "High":

            return 1.5

        if priority == "Medium":

            return 1.1

        return 1.0

近期加权

框架使用 modified 字段自动提供基于时间的近期加权：

# The modified field is used for calculating document age

# Recent documents get higher scores:

# - Last 24 hours: 1.8x boost

# - Last 7 days: 1.5x boost

# - Last 30 days: 1.2x boost

# - Last 90 days: 1.1x boost

# - Older documents: gradually decreasing boost

# If your doctype uses a different timestamp field, map it to modified:

INDEXABLE_DOCTYPES = {

    "GP Discussion": {

        "fields": ["name", "title", "content", {"modified": "last_post_at"}, "project"],

    },

    "Article": {

        "fields": ["name", "title", "content", {"modified": "published_date"}, "category"],

    }

}

文档准备

覆盖 prepare_document() 以进行自定义文档处理：

def prepare_document(self, doc):

    """Custom document preparation"""

    document = super().prepare_document(doc)

    if not document:

        return None

    # Add computed fields

    if doc.doctype == "Task":

        # Combine multiple fields into content

        content_parts = [

            doc.description or "",

            doc.notes or "",

            "\n".join([comment.content for comment in doc.get("comments", [])])

        ]

        document["content"] = "\n".join(filter(None, content_parts))

        # set fields that might be stored in another table

        document["category"] = get_category_for_task(doc)

    return document

拼写纠正

框架内置了使用三元组相似度的拼写纠正功能：

# Spelling correction happens automatically

search_result = search.search("projetc managment")  # Will find "project management"

# Access correction information

print(search_result["summary"]["corrected_words"])

# Output: {"projetc": "project", "managment": "management"}

内容处理

HTML 内容会自动使用 BeautifulSoup 进行清理和处理：

# Complex HTML content like this:

html_content = """

<div class="article">

<h1>API Documentation</h1>

<p>Learn how to integrate with our <a href="/api">REST API</a>.</p>

    <img src="/images/api-flow.png" alt="API workflow diagram">

<ul>

<li><strong>Authentication:</strong> Use <code>Bearer tokens

Rate limiting: 1000 requests/hour

    

See our code examples for details.

Method
POST

    analytics.track('page_view');

.hidden { display: none; }