开源大数据平台E-MapReduce：DLF Paimon表向量检索

启用分布式 Global Index 查询

在执行向量查询的每个连接中设置以下会话变量。

SET paimon_global_index_scan_stage = 2;

参数说明如下。

编写查询向量

在两阶段查询路径中，查询向量必须使用原生数组字面量。

[0.12, 0.34, 0.56, 0.78]

不要使用以下写法。

CAST('[0.12, 0.34, 0.56, 0.78]' AS ARRAY<FLOAT>)

在两阶段索引表达式的序列化链路中，CAST(string AS ARRAY<FLOAT>) 可能导致维度校验失败或 Global Index 未生效。

TopK 向量检索

余弦相似度越大表示越相似，因此按降序排序。

SELECT
    item_id,
    approx_cosine_similarity(
        embedding,
        [0.12, 0.34, 0.56, 0.78]
    ) AS score
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
ORDER BY score DESC
LIMIT 10;

L2 距离越小表示越相似，因此按升序排序。

SELECT
    item_id,
    approx_l2_distance(
        embedding,
        [0.12, 0.34, 0.56, 0.78]
    ) AS distance
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
ORDER BY distance ASC
LIMIT 10;

内积越大表示越相似，因此按降序排序。

SELECT
    item_id,
    approx_inner_product(
        embedding,
        [0.12, 0.34, 0.56, 0.78]
    ) AS score
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
ORDER BY score DESC
LIMIT 10;

要命中 TopK Global Index，查询需要满足以下形态。

• 评分函数为 approx_l2_distance、approx_cosine_similarity 或 approx_inner_product。

• 评分函数的一侧是已创建向量索引的向量列，另一侧是常量浮点数组。

• ORDER BY 中只包含一个评分表达式。

• L2 距离使用升序，余弦相似度和内积使用降序。

标量与向量联合检索

以下示例先按文档类型过滤，再执行余弦相似度 TopK 检索。

SELECT
    item_id,
    title,
    approx_cosine_similarity(
        embedding,
        [0.12, 0.34, 0.56, 0.78]
    ) AS score
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
WHERE category = 'document'
ORDER BY score DESC
LIMIT 10;

过滤条件的执行时机分为两类。

• Prefilter：过滤列上存在兼容的 Paimon Bitmap/BTree Global Index，且谓词形态可下推。系统先过滤候选集合，再执行向量检索，有利于保持过滤后 TopK 的召回效果。

• Postfilter：过滤条件不能下推到 Global Index，在向量召回后执行。候选结果经过滤后可能少于 LIMIT，也可能降低最终的 Recall@K。

常见的可预过滤条件如下。

预热返回列缓存

向量索引返回 Row ID 后，还需要读取查询投影中的标量列。如果查询只返回 item_id，可以预热对应列的 row-scalar 缓存。

SET query_timeout = 3600;

CACHE SELECT item_id
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
PROPERTIES (
    "cache_target" = "row_scalar",
    "verbose" = "true"
);

部分后续分支可能使用 rowid_scalar 作为 cache_target 的取值。如果服务端提示参数取值不支持，请以错误信息中列出的有效值为准。

如果查询还会返回大文本或其他列，可以根据实际投影评估是否执行整表预热。

CACHE SELECT *
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
PROPERTIES ("verbose" = "true");

检查 Global Index 是否生效

先确认当前连接的会话变量。

SHOW VARIABLES LIKE 'paimon_global_index_scan_stage';
SHOW VARIABLES LIKE 'ann_params';

再对查询执行 EXPLAIN。

EXPLAIN
SELECT item_id
FROM <DLF_CATALOG>.<DATABASE_NAME>.<PAIMON_TABLE>
ORDER BY approx_cosine_similarity(
    embedding,
    [0.12, 0.34, 0.56, 0.78]
) DESC
LIMIT 10;

检查执行计划中是否包含 Paimon Global Index 的索引扫描阶段和后续的数据扫描，而不是直接对全表执行普通扫描。不同构建版本的节点名称可能不同，建议结合 Query Profile 中的索引阶段耗时、索引返回行数、回表读取量和最终扫描行数一起判断。

验证召回率

绝对 Recall@K 的计算方式如下。

Recall@K = |ANN 返回的 TopK ID ∩ 精确 ground truth TopK ID| / K

用于 ground truth 的数据必须与目标 Paimon 表来自同一份数据快照，并使用完全相同的 ID 映射、向量模型和距离度量。如果 ground truth 中的 ID 与湖表 ID 不一致，不能对外发布绝对召回率。

暂时没有有效 ground truth 时，可以将高质量参数下的结果作为调优基线，计算结果集合重合率。但该指标只能标注为「相对基线一致性」，不能标注为产品 Recall@K。

报向量维度不匹配，如何排查？

1. 确认查询数组的元素数量与索引维度一致。

2. 确认使用原生数组字面量，没有使用 CAST(string AS ARRAY<FLOAT>)。

3. 确认湖表向量列和向量索引来自同一份数据及同一个 Embedding 模型。

4. 确认数组中没有非法浮点值。

Global Index 未生效，如何排查？

1. 确认当前连接已设置 paimon_global_index_scan_stage = 2。

2. 确认 Paimon 表元数据中存在向量索引。

3. 确认 ORDER BY 中只有一个受支持的近似评分表达式。

4. 确认查询向量为常量原生浮点数组。

5. 对查询执行 EXPLAIN，排除表达式改写、额外排序列或不支持的过滤形态。

过滤后返回结果少于 LIMIT，如何处理？

通常说明部分条件只能在向量召回后执行 Postfilter。可以通过以下方式处理。

• 为过滤列创建兼容的 Paimon Bitmap/BTree Global Index，使条件进入 Prefilter。

• 同时验证 Recall@K、查询延迟和回表数据量，避免只解决结果数量而造成过高的资源开销。

首次查询明显较慢，是什么原因？

首次查询可能包含索引文件、元数据和返回列数据的远端读取。建议分别记录冷缓存和预热后的结果，并检查计算节点的 Data Cache、row-scalar 缓存和共享存储访问情况。

提高并发后 QPS 不再增长，如何排查？

• 查看计算节点的 CPU、内存、网络和对象存储吞吐是否饱和。

• 查询并发和索引分片并发是否造成线程超卖。

• 关注 P95/P99 延迟和错误数，而不是只观察平均 QPS。

• 保持查询投影最小化，避免返回不必要的大字段。