当数据分析师面对数百万条客户记录、销售备注或日志文本时，传统的 LIKE '%keyword%' 查询往往力不从心。DuckDB 作为面向分析型工作负载的嵌入式数据库，在 0.10 版本后引入了原生 FTS（Full-Text Search）扩展，为单机器环境提供了无需部署 Elasticsearch 即可实现的全文检索能力。本文系统梳理从环境准备到查询优化的完整技术路径。
一、FTS 扩展的安装与基础架构
DuckDB 的全文搜索功能通过独立的扩展实现，首次使用时会从官方扩展仓库自动下载。显式安装的步骤极为简洁：
INSTALL fts;
LOAD fts;
扩展加载后，系统会增加两类核心组件：一是用于管理索引的 PRAGMA 语句（create_fts_index 与 drop_fts_index），二是用于执行检索的 match_bm25 函数。值得注意的是，DuckDB FTS 采用倒排索引（Inverted Index）作为底层数据结构，这与 SQLite FTS5 的实现思路一致，但索引存储于 DuckDB 专属的模式（schema）之中 —— 若在表 main.notes 上创建索引，系统会自动创建名为 fts_main_notes 的独立模式存放索引数据。
在索引创建前，需要确保目标表已存在且包含可索引的文本列。一个典型的业务场景是客户关系管理系统中的 notes 表：
CREATE TABLE notes (
id INTEGER PRIMARY KEY,
title VARCHAR,
body TEXT,
created_at TIMESTAMP
);
建议将需要全文检索的列显式声明为 VARCHAR 或 TEXT 类型，以便扩展正确识别。DuckDB FTS 支持同时索引多个文本列，检索时会综合各列的匹配结果计算最终相关度得分。
二、倒排索引的构建策略
创建全文索引通过 PRAGMA create_fts_index 语句完成，核心参数包括词干提取器、停用词表以及文本预处理选项：
PRAGMA create_fts_index(
'notes', -- 表名
'id', -- 主键列
'title', 'body', -- 要索引的列
stemmer='porter', -- 词干提取器：英文
stopwords='english', -- 停用词表
ignore='(\\.|[^a-z])+', -- 正则过滤规则
strip_accents=1, -- 移除重音符号
lower=1 -- 转为小写
);
词干提取器（stemmer）的选择直接影响检索效果。DuckDB FTS 内置超过二十种语言的词干提取器，包括 porter（英文默认）、german、french、spanish、dutch 等。对于多语言混合的业务数据，建议根据主要语种选择对应的 stemmer，或在 stemmer='none' 禁用词干化以保留原始词形。停用词表默认为内置的 571 个英文停用词（如 "the"、"is"、"at"），可通过 stopwords='none' 禁用，或创建自定义停用词表以适应特定业务词汇。
关于索引大小的经验法则：根据实际测试，FTS 索引通常占原始文本大小的 30% 至 50%。这意味着 1GB 的文本数据需要额外约 300MB 至 500MB 的存储空间。在规划磁盘容量时应将此纳入考量。
三、BM25 检索与结果排序
索引创建完成后，即可使用 match_bm25 函数执行搜索。该函数返回每个文档与查询词的相关度得分，得分越高表示匹配度越好：
SELECT id, title,
fts_main_notes.match_bm25(id, 'pipeline revenue') AS score
FROM notes
WHERE score IS NOT NULL
ORDER BY score DESC;
BM25（Best Matching 25）是信息检索领域的经典算法，被 Elasticsearch、OpenSearch 等主流搜索引擎广泛采用。DuckDB 实现的 BM25 支持两个可调参数：k1（默认 1.2）控制词频饱和度，b（默认 0.75）控制文档长度归一化程度。在大多数场景下使用默认值即可获得合理结果，但可根据数据特点进行微调 —— 若文档长度差异较大，可适当增大 b 值以强化长度归一化效果。
DuckDB FTS 还支持布尔查询语法：
-- 必须同时包含两个词
SELECT id, title, fts_main_notes.match_bm25(id, 'pipeline AND revenue') AS score
FROM notes WHERE score IS NOT NULL ORDER BY score DESC;
-- 包含任一词即可
SELECT id, title, fts_main_notes.match_bm25(id, 'churn OR expansion') AS score
FROM notes WHERE score IS NOT NULL ORDER BY score DESC;
-- 排除特定词
SELECT id, title, fts_main_notes.match_bm25(id, 'customer NOT churn') AS score
FROM notes WHERE score IS NOT NULL ORDER BY score DESC;
在实际业务场景中，全文检索往往需要与常规 SQL 谓词结合使用。DuckDB 的强项在于这种混合查询场景 —— 可以在 FTS 检索前先用 WHERE 子句预过滤非文本条件（如日期范围、部门筛选），大幅缩小扫描范围：
SELECT id, title, created_at,
fts_main_notes.match_bm25(id, 'expansion contract') AS score
FROM notes
WHERE score IS NOT NULL
AND created_at > '2026-01-01'
AND department = 'sales'
ORDER BY score DESC
LIMIT 10;
这种「先过滤后检索」的策略是优化大规模数据查询的关键技巧。
四、索引维护与增量更新方案
当前版本的 DuckDB FTS 存在一个重要限制：索引不会随源表的数据变更自动更新。插入新行或更新已有记录后，必须手动重建索引才能使新增内容可被检索：
PRAGMA drop_fts_index('notes');
PRAGMA create_fts_index('notes', 'id', 'title', 'body');
这一限制决定了不同的业务场景应采用不同的更新策略。对于日志分析等只增不减的写入模式，建议按固定周期（如每日凌晨）执行重建操作，避开业务高峰期。对于交互式应用（如 CRM 系统），应在批量导入操作完成后触发一次索引重建。有条件的情况下，可考虑在写入频率较低的备用副本上维护 FTS 索引，以减少主库的业务影响。
五、性能基准与优化参数
根据社区测试数据，DuckDB FTS 的查询性能在现代硬件上表现可观：百万级行数据的 BM25 搜索通常在 100 毫秒以内完成；千万级数据量下，响应时间约在 200 毫秒至 500 毫秒之间。若查询延迟超出预期，可尝试以下优化手段：
第一，减少索引列数量。仅对确有检索需求的列创建索引，避免将大量无关文本列纳入索引，可显著降低倒排索引的体积与扫描开销。第二，充分利用前置过滤。如前所述，在调用 match_bm25 前先用结构化条件（如时间范围、类别标识）限定结果集，可使 FTS 仅在经过筛选的子集上执行评分计算。第三，合理使用 LIMIT 子句。DuckDB 的查询优化器会在检测到 LIMIT 时提前终止评分计算，避免对全量匹配结果进行排序。
六、适用场景与方案选型
DuckDB FTS 最适合以下业务场景：数据规模在单机可承载范围内（通常建议低于数百 GB）、已有 DuckDB 作为分析数据库、希望在 SQL 层面统一实现搜索与聚合、需要快速构建原型或内部工具。与 Elasticsearch 相比，DuckDB FTS 的优势在于零运维成本、原生 SQL 集成以及免费使用；其劣势则包括缺乏模糊匹配（typo 容忍）、不支持实时增量更新、以及单机存储上限。若业务需要分布式扩展、实时数据更新或高级语义匹配，则应考虑 Elasticsearch、Meilisearch 等专用搜索引擎。
七、实践建议
在生产环境中部署 DuckDB FTS 时，有几个工程细节值得关注。首先，创建索引前务必确认目标表的结构已稳定，索引创建后新增的 VARCHAR 列不会自动纳入索引范围。其次，可为不同业务域的检索需求分别创建独立的 FTS 索引，避免单一索引承载过多样化的文本字段。第三，由于索引不自动更新，建议将索引重建操作纳入数据管道的监控体系，确保异常情况可被及时发现。
资料来源：本文技术细节参考 DuckDB 官方文档 Full-Text Search Extension（https://duckdb.org/docs/stable/core_extensions/full_text_search）以及 Dench 博客的实战指南。