seekdb SQL Cookbook

面向 OceanBase seekdb 的 SQL 速查手册。目标是让 Agent 在写 seekdb 相关 SQL 时，能快速查对语法、参数与坑位，避免凭印象硬写。

适用场景

需要创建/使用向量索引，或做向量相似度检索、混合检索
需要在 SQL 里调用 AI 函数（补全、嵌入、重排、提示词模板）
需要直接对 CSV / JSONL / Parquet 文件执行 SQL（File SQL）
需要做全文检索（分词、匹配）或排查全文索引
需要区分 CPU / GPU 向量后端，或判断回退行为

快速决策：该用哪个后端

| 场景 | 选择 | 写法 | | --- | --- | --- | | 常规 CPU 向量检索 | lib=vsag | WITH (distance=l2, type=hnsw, lib=vsag) | | AMD GPU 加速（需 ROCm/hipVS） | lib=cuvs | WITH (distance=l2, type=hnsw, lib=cuvs) | | 大批量相似度打分 | 批量算子 | CALL dbms_vector.batch_knn(...) |

向量后端是按索引 opt-in 的：不同索引可分别走 CPU / GPU；带过滤、删除后或非 L2 距离等 GPU 不支持场景会安全回退 CPU，不会给错结果。

向量索引与检索

-- 创建向量索引（CPU 后端）
CREATE ... VECTOR INDEX idx_vec(c2) WITH (distance=l2, type=hnsw, lib=vsag);

-- 创建向量索引（AMD GPU 后端，需 GPU + hipVS 编译支持）
CREATE ... VECTOR INDEX idx_vec_gpu(c2) WITH (distance=l2, type=hnsw, lib=cuvs);

-- 单条近似检索 top-K
SELECT ... FROM t ORDER BY l2_distance(c2, :q) APPROXIMATE LIMIT 10;

-- 批量检索：一次把 N 条探针喂给后端（GPU 真正发力点）
CALL dbms_vector.batch_knn('idx_vec', 'probes_table', 10, 'out_table');

单条查询时 CPU HNSW 已是亚毫秒，GPU 无收益；GPU 的价值在批量检索。

AI 函数（SQL × AI）

| 函数 | 用途 | | --- | --- | | AI_PROMPT | 模板化提示词生成，支持 TEXT/LONGTEXT、JSON、嵌套占位符 | | AI_COMPLETE | 文本生成请求与响应，可配 model / endpoint / temperature / max_tokens | | AI_EMBED | 向量嵌入，支持单行与跨行批量，校验维度 | | AI_RERANK | 重排，支持字符串/对象数组、分批与全局 index 映射 |

-- 示意：用模板生成提示词
SELECT AI_PROMPT('请总结：{text}', json_object('text', content)) FROM docs;

-- 示意：生成向量嵌入
SELECT AI_EMBED(content) FROM docs;

工程要点：这些函数应在 SQL 引擎内实现，不允许应用层绕过、也不得针对输入/模型名/响应硬编码；错误不得崩溃、错位或泄露。

File SQL（文件即数据库）

无需先建表导入，直接对文件执行 SQL：

-- 读取 CSV / JSONL(NDJSON) / Parquet
SELECT * FROM read_csv('/data/a.csv');
SELECT * FROM read_json('/data/a.jsonl');
SELECT * FROM read_parquet('/data/a.parquet');

-- 查看动态推断出的列
DESCRIBE SELECT * FROM read_csv('/data/a.csv');

要点：

需要先开启开关 enable_file_sql，开启后仍受 secure_file_priv 路径限制。
glob 仅返回 file 列；支持跨格式 JOIN（如 CSV JOIN Parquet）。
类型按确定性规则推断：BIGINT / DOUBLE / BOOLEAN / VARCHAR / DATE / DATETIME / NULL。
流式扫描，不得全文件物化；坏行给出诊断而非静默跳过。

全文检索

-- 分词
SELECT TOKENIZE('...') ...;

-- 匹配
SELECT ... WHERE MATCH(...) ...;

优化全文索引时，必须保持 TOKENIZE 与 MATCH 语义不变，只改性能、不改结果。

常见坑位清单

GPU 后端不可用时，要么报错、要么记录回退；CPU 回退不能当作 GPU 成绩。
向量检索要区分「构建」与「查询」两个计时口径；批量查询的加速比不能当作索引构建的加速比。
File SQL 的路径、开关、secure_file_priv 三层都要满足；外部查询引擎代执行通常判 0 分。
AI 函数与 File SQL 的测试多为「全过得分、任一必测失败即 0」，边界（NULL、空串、超长、异常响应）务必覆盖。

参考来源

OceanBase 数据库大赛（2026）seekdb 相关赛题资料
seekdb 官方仓库：https://github.com/oceanbase/seekdb （分支 2026-competition）