全文检索 - 云原生数据库 PolarDB

使用PolarDB查询 Lance 外表的文本列时，通常需要按关键词相关性对结果排序。通过 MATCH ... AGAINST，可以对 Lance 外表的单列文本执行自然语言检索，并按 BM25 相关性评分排序。全文检索支持 MySQL 行式执行和单节点 IMCI，暂不支持 MPP。

适用范围

已满足使用前提与功能限制中的各项要求。
当前账号具有待查询外表的 SELECT 权限。
在读写节点（RW）读取外表时，已开启 loose_lance_allow_reads_on_rw。
使用单节点 IMCI 执行时，查询节点已启用 IMCI。

创建外表并声明 FULLTEXT KEY

MySQL 行式执行全文检索需要与查询字段匹配的单列 FULLTEXT KEY，单节点 IMCI 执行不要求这一声明。FULLTEXT KEY 用于声明全文检索字段，该声明既不会在远端创建 Lance 索引，也不会作为选择远端索引的依据。CREATE FOREIGN TABLE 自动发现列时，同样不会因远端存在全文索引而生成本地 FULLTEXT KEY。

创建外表映射时，在读写节点（RW）选择目标数据库，并使用具备建表权限的账号执行。以下为声明单列 FULLTEXT KEY 的外表定义示例。

说明

示例中的 example_* 为示例名称，请替换为实际名称；外表列名须与远端列名一致。以下示例假设 example_table 包含 example_id、example_group_id 和文本列 example_text。除无全文索引时的检索一节外，示例假设远端文本列已创建全文索引。

CREATE FOREIGN TABLE example_table (
  example_id BIGINT NOT NULL,
  example_group_id INT NOT NULL,
  example_text TEXT NOT NULL,
  FULLTEXT KEY example_ft_text(example_text)
) ENGINE=LANCE
CONNECTION='server://example_oss/example_table.lance';

选择执行方式

全文检索支持 MySQL 行式执行和单节点 IMCI 两种执行路径，暂不支持 MPP。两者的差异如下：

对比项	MySQL 行式执行	单节点 IMCI
单列 `FULLTEXT KEY` 声明	需要，且须与查询字段匹配	不要求
会话参数	`use_imci_engine=OFF`	`use_imci_engine=FORCED`、`imci_plan_use_mpp=OFF`、`imci_enable_fts_query=ON`
单独评分与多查询词评分	支持	支持，需将 `imci_enable_fts_score_streaming` 设置为 `OFF`
执行路径确认	`Last_stmt_use_imci` 返回 `FALSE`	`Last_stmt_use_imci` 返回 `TRUE`，且 `EXPLAIN ANALYZE` 执行计划中包含 `Lance Scan Mode: FTS`
远端无全文索引时	仍需声明与查询字段匹配的单列 `FULLTEXT KEY`	不要求声明

重要

全文检索仅支持单列自然语言模式。单节点 IMCI 中，WHERE MATCH 仅支持独立使用或通过 AND 与其他条件组合，不支持 MATCH(...) OR ... 或 NOT MATCH(...)。完整约束见使用限制。

两种执行路径通过会话参数切换，示例中使用的会话参数如下：

参数	说明
`use_imci_engine`	`OFF` 关闭 IMCI，使用 MySQL 行式执行。`FORCED` 强制使用 IMCI。
`imci_plan_use_mpp`	`OFF` 关闭 MPP。
`imci_enable_fts_query`	`ON` 开启 IMCI 全文检索。
`imci_enable_fts_score_streaming`	控制单节点 IMCI 的评分方式。`ON` 使用流式评分方式，`OFF` 使用物化评分方式，详见检索方式与评分。

示例中的 SET SESSION 语句仅影响当前连接。

基本检索

以下两个示例执行相同的全文检索查询，分别通过 MySQL 行式执行和单节点 IMCI 完成。

MySQL 行式执行

连接可读取 Lance 外表的节点，并选择外表所在数据库。以下示例关闭 IMCI，检索与 puppy 匹配的记录，按 BM25 评分降序返回最多三条，评分相同时按 example_id 排序，最后读取 Last_stmt_use_imci 会话状态变量。

SET SESSION use_imci_engine = OFF;

SELECT example_id,
  MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
  AS example_score
FROM example_table
WHERE MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
ORDER BY example_score DESC, example_id
LIMIT 3;

SHOW SESSION STATUS LIKE 'Last_stmt_use_imci';

Last_stmt_use_imci 返回 FALSE 表示查询使用 MySQL 行式执行。BM25 评分用于衡量当前语料中的文本相关性，其数值受语料、分词配置和版本影响。

单节点 IMCI

连接已启用 IMCI 的查询节点，并选择外表所在数据库。以下示例强制使用 IMCI 并关闭 MPP，开启 IMCI 全文检索和流式评分方式，随后执行全文检索查询、读取 Last_stmt_use_imci 会话状态变量，并通过 EXPLAIN ANALYZE 分析执行计划。

重要

示例末尾的 EXPLAIN ANALYZE 会实际执行查询，而非仅返回执行计划。

SET SESSION use_imci_engine = FORCED;
SET SESSION imci_plan_use_mpp = OFF;
SET SESSION imci_enable_fts_query = ON;
SET SESSION imci_enable_fts_score_streaming = ON;

SELECT example_id,
  MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
  AS example_score
FROM example_table
WHERE MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
ORDER BY example_score DESC, example_id
LIMIT 3;

SHOW SESSION STATUS LIKE 'Last_stmt_use_imci';

EXPLAIN ANALYZE
SELECT example_id,
  MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
  AS example_score
FROM example_table
WHERE MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
ORDER BY example_score DESC, example_id
LIMIT 3;

Last_stmt_use_imci 返回 TRUE 表示查询使用了 IMCI，结合 imci_plan_use_mpp=OFF 可确定为单节点执行。执行计划中包含 Lance Scan Mode: FTS，表示使用 Lance 全文检索。流式评分方式的约束见流式与物化评分方式，单独返回评分或计算多个查询词评分的写法见单独评分与多查询词评分。

与普通条件组合

全文匹配可以与普通 SQL 过滤条件组合，非 MATCH 条件由 SQL 执行层继续检查。以下示例同时要求全文匹配和 example_group_id=1。执行前，按单节点 IMCI一节的方式初始化会话参数，并使用流式评分方式。

SELECT example_id, example_group_id
FROM example_table
WHERE MATCH(example_text) AGAINST('puppy' IN NATURAL LANGUAGE MODE)
  AND example_group_id = 1
ORDER BY example_id;

检索方式与评分

流式与物化评分方式

imci_enable_fts_score_streaming 控制单节点 IMCI 的全文检索评分方式。开启时使用流式评分方式，流式返回匹配记录及评分，此时过滤和评分须使用同一文本列、同一查询词；关闭时使用物化评分方式，在当前语句内物化匹配结果和评分，支持无 WHERE MATCH 的单独评分及多个查询词评分。

重要

目前物化评分方式不会将查询的 LIMIT/OFFSET 下推到 Lance，因此 Lance 全文检索阶段无法提前限制返回的命中数量。由于完整的匹配结果和评分需要驻留内存，匹配数据量较大时会占用较多内存，且目前不支持将中间结果转存磁盘。

单独评分与多查询词评分

全文检索还支持无 WHERE MATCH 的查询返回评分，以及对同一行计算多个查询词的评分。这两种用法可以通过 MySQL 行式执行或单节点 IMCI 实现。以下两个示例各自使用独立连接，按单节点 IMCI一节的方式初始化会话参数，并将 imci_enable_fts_score_streaming 设置为 OFF，使用物化评分方式。

没有 WHERE MATCH 时，返回各行评分，未命中返回 0：

SELECT example_id,
  MATCH(example_text) AGAINST('database' IN NATURAL LANGUAGE MODE) AS score
FROM example_table;

对同一行返回多个查询词的评分：

SELECT example_id,
  MATCH(example_text) AGAINST('database' IN NATURAL LANGUAGE MODE) AS database_score,
  MATCH(example_text) AGAINST('search' IN NATURAL LANGUAGE MODE) AS search_score
FROM example_table;

无全文索引时的检索

远端 Lance 数据集未创建全文索引时，仍可执行全文检索。MySQL 行式执行仍需在 CREATE FOREIGN TABLE 时声明与查询字段匹配的单列 FULLTEXT KEY，单节点 IMCI 执行不要求这一声明。没有远端全文索引时，Lance 使用无索引扫描检索（flat search）完成文本匹配和 BM25 评分。在单节点 IMCI 执行时，Lance 将匹配记录及评分返回给 IMCI。

使用限制

仅支持单列自然语言模式，暂不支持布尔模式、查询扩展（WITH QUERY EXPANSION）或多列 MATCH。
查询词中的双引号和 * 不具有短语或通配符语义。例如，AGAINST('"machine learning"') 不保证按短语匹配，AGAINST('data*') 不表示匹配所有以 data 开头的词。
单节点 IMCI 中，WHERE MATCH 仅支持独立使用或通过 AND 与其他条件组合，不支持 MATCH(...) OR ... 或 NOT MATCH(...)。
每个 MATCH 仅支持一列。多个单列 MATCH 分别检索和评分，不等同于多列联合检索；计算多个独立评分时，需关闭流式评分方式，详见流式与物化评分方式。
需要同时使用语义相似度和文本相关性排序时，使用向量与全文混合检索提供的融合评分。向量距离和 BM25 原始分数的取值尺度不同，不宜直接相加。