向量数据库数据库【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址https://gitcode.com/GitHub_Trending/sq/sqlite-vec点击查看免费下载vec0是 sqlite-vec 扩展提供的原生向量虚拟表它允许你在建表时声明向量列与普通列并把 K 近邻KNN检索与过滤条件压缩进一条 SQL。本文以vec0虚拟表为绝对主线系统讲解在向量列之外如何用 metadata 列、partition key 列与 auxiliary 列存放非向量数据——覆盖声明语法、类型限制、KNN 查询中的行为、性能取舍与源码级实现细节帮助你为 RAG、语义搜索、图像检索等场景设计出正确的表结构。为什么vec0需要区分三种普通列向量检索场景中绝大多数表除了向量本身还需要保存业务字段文档的id、所属user_id、标签genre、正文contents、图片的原始字节等。如果全部塞进向量索引既浪费空间又会让过滤变慢如果全部丢到外部表则每次 KNN 都要JOIN回去。sqlite-vec 在vec0虚拟表中提供了三种存储非向量列的方案metadata 列、partition key 列和auxiliary 列。三者的核心差异在于列类型描述优点限制Metadata 列与向量一起存储 boolean / integer / float / text 数据可参与 KNN 查询的WHERE条件全表扫描较慢长文本超过 12 字符时略有浪费Auxiliary 列在独立内部表中存储任意类型数据省去外部JOIN可直接出现在SELECT结果中不能出现在 KNN 查询的WHERE子句中Partition Key 列按指定键在内部对向量索引分片让选择性查询快很多使用不当会造成过度分片、拖慢 KNN每个唯一分区键值应包含数百个向量一个同时使用三种方案的建表示例来自官方文档create virtual table vec_chunks using vec0( document_id integer partition key, contents_embedding float[768], -- partition key column由 partition key 关键字标记 user_id integer partition key, -- metadata column外观与普通列定义一致 label text, -- auxiliary column由 前缀标记 contents text );在源码层面sqlite-vec.c通过vec0_user_column_kind枚举区分这四类用户列vector / partition / auxiliary / metadata并在构造阶段vec0Create的表定义解析循环对每个argv[i]依次尝试解析为向量列、分区键列、主键列、auxiliary 列或 metadata 列。下面分别深入讲解每种方案的用法与底层行为。Metadata 列让 KNN 查询携带过滤条件声明方式与支持的类型Metadata 列就是vec0表定义中那些普通列它们与向量列一起被索引并允许你在 KNN 查询中追加额外的WHERE约束。声明语法与普通建表一致先是列名再是类型。所有 metadata 列都是严格类型strictly typed的仅支持以下四种类型TEXT—— 文本与字符串INTEGER—— 8 字节整数FLOAT—— 8 字节浮点数BOOLEAN—— 1 比特的0或1类型名大小写不敏感。从解析器vec0_parse_metadata_column_definition可以看到更多别名bool、int64、integer64、int、double、float64、f64等写法均被接受源码注释还预留了 future 的blob、date、datetime类型。需要注意metadata 列不支持UNIQUE、NOT NULL等附加约束且每个vec0虚拟表最多声明 16 个 metadata 列——上限在源码中以宏定义VEC0_MAX_METADATA_COLUMNS 16固化sqlite-vec.c对应的构造参数超限测试可见 tests/test-metadata.py。典型建表示例电影语义搜索create virtual table vec_movies using vec0( movie_id integer primary key, synopsis_embedding float[1024], genre text, num_reviews int, mean_rating float, contains_violence boolean );其中genre、num_reviews、mean_rating、contains_violence都是 metadata 列。在 KNN 查询中做过滤带 metadata 约束的 KNN 查询示例select * from vec_movies where synopsis_embedding match [...] and k 5 and genre scifi and num_reviews between 100 and 500 and mean_rating 3.5 and contains_violence false;WHERE子句中的前两个条件synopsis_embedding match与k 5标记了这是一条 KNN 查询其余条件则是 metadata 约束sqlite-vec 会在 KNN 计算过程中识别并应用它们。也就是说上面的查询最多返回 5 行且这 5 行全部满足其 metadata 列上的所有WHERE约束。支持的操作符KNN 查询中metadata 列的WHERE条件只支持以下操作符等于!不等于大于大于或等于小于小于或等于使用其他操作符如IS NULL、LIKE、GLOB、REGEXP或任何标量函数都会导致报错或产生错误结果。此外BOOLEAN 列只支持和!两种操作符。这些限制在源码中有对应枚举体现vec0_metadata_operator定义了EQ / GT / LE / LT / GE / NE并额外包含IN操作符而官方文档明确说明的约束即、!、,、、。tests/test-metadata.py 中则逐一验证了name ddd、name ddd、name fff、name fff、name aaa等约束在k 5下的行为。底层存储与长文本浪费的由来从源码结构看metadata 值并不是简单地和每行向量塞在一起vec0_vtab结构体为每个 metadata 列维护了_metadatachunksNN影子表VEC0_SHADOW_METADATA_N_NAME读取时通过vec0_result_metadata_value_for_rowid用sqlite3_blob_open做 BLOB 级随机读取较长的 text 值还会落到额外的_metadatatextNN影子表。这解释了文档中长字符串超过 12 字符时略低效的说明——短值内联在 chunk 中长值需要跳转到独立文本表读取。Partition Key 列按键分片以加速选择性查询原理与适用场景Partition Key 列允许你基于某个键在内部对向量索引分片。KNN 查询中只要出现对 partition key 列的约束搜索就会被限制在对应分片内。典型场景一个存放大量文档向量的库每篇文档属于某个用户而用户只能检索自己的文档。若每次只为一位用户检索却要对全部文档做暴力扫描显然浪费。于是可以按user_id分区create virtual table vec_documents using vec0( document_id integer primary key, user_id integer partition key, contents_embedding float[1024] )KNN 查询时在WHERE中限定用户select document_id, user_id, distance from vec_documents where contents_embedding match :query and k 20 and user_id 123;sqlite-vec 会识别user_id 123这一约束在 KNN 搜索前对向量做预过滤。由于相同 partition key 值的向量在物理上彼此相邻存放这是一个很快的操作。再如按发布时间分区的新闻标题搜索多数用户只关心某个时间段过去十年或奥巴马执政期间的文章可建表如下create virtual table vec_articles using vec0( article_id integer primary key, published_date text partition key, headline_embedding float[1024] );对应 KNN 查询select article_id, published_date, distance from vec_articles where headline_embedding match :query and published_date between 2009-01-20 and 2017-01-20; -- 奥巴马执政期间注意partition key 列的类型并不限于整数text同样支持如这里的published_date。过度分片警告务必小心过度使用 partition key 会导致过度分片over-sharding和更慢的 KNN 查询。经验法则每个唯一 partition key 值最好关联约数百个向量。在上面的例子中确保每位用户都有几十或上百篇文档或每天有几十、最好上百篇文章。如果数据达不到这个量级且查询变慢就应改用更宽泛的分区键比如organization_id或published_month。每个vec0虚拟表最多可声明 4 个 partition key 列宏VEC0_MAX_PARTITION_COLUMNS 4见 sqlite-vec.c。但请谨慎使用超过 1 个 partition key 列向量会沿每个唯一键组合被分片分区键越多越容易过度分片。tests/test-partition-keys.py 的test_constructor_limit正是用 5 个分区键来验证 4 个的上限。源码行为支持的操作符、类型检查与限制从vec0_partition_operator枚举可见partition key 列支持的约束比文档示例更丰富包括EQ、GT、LE、LT、GE、!NE六种且支持BETWEEN这类组合。源码注释特别提醒如果更新了这些值请同步更新 ARCHITECTURE.md 文档。另外从测试与源码可以确认两点实现事实类型是严格检查的向 partition key 列插入错误类型的值会直接报错Parition key type mismatch但NULL 是允许的——见 tests/test-partition-keys.py。当前不支持 UPDATE 分区键源码在更新逻辑中明确报出UPDATE on partition key columns are not supported yet.sqlite-vec.c所以业务上应把分区键视为行创建后不可变的属性。Auxiliary 列免 JOIN 取回大字段概念与声明语法Auxiliary 列把额外的、不参与索引的数据存放在独立的内部表中。它们适合那些永远不会出现在 KNN 查询WHERE子句里、但又需要在结果集中直接取回的大块元数据——省去了外部JOIN。Auxiliary 列通过在列定义前加前缀声明create virtual table vec_chunks using vec0( contents_embedding float[1024], contents text ); select rowid, contents, distance from vec_chunks where contents_embedding match :query and k 10;这里把每个 chunk 的文本正文存进contentsauxiliary 列。执行 KNN 查询时直接在SELECT子句引用contents列就能拿到最相关 chunk 的原始文本。同样的思路可以用于图像嵌入场景把原始图片文件放进BLOB类型的 auxiliary 列create virtual table vec_image_chunks using vec0( image_embedding float[1024], image blob ); select rowid, contents, distance from vec_chunks where contents_embedding match :query and k 10;注意上面两条示例的 SELECT 均为示意性写法查询时rowid、distance之外引用的是各自表中声明的 auxiliary 列名如image。适用与不适用的数据总体而言auxiliary 列适合大型文本、BLOB、URL 或其它不会进入 KNN 查询WHERE子句的数据类型凡是经常出现在SELECT中、但绝不会出现在WHERE中的列都是 auxiliary 列的好候选。反过来auxiliary 列不能出现在 KNN 查询的WHERE子句中这是它与 metadata 列最本质的功能差异。每个vec0虚拟表最多可声明 16 个 auxiliary 列宏VEC0_MAX_AUXILIARY_COLUMNS 16sqlite-vec.c超限测试见 tests/test-auxiliary.py。源码行为类型、存储与增删改Auxiliary 列的解析器vec0_parse_auxiliary_column_definition首先检查第一个 token 是否为随后把列类型归一化为四类之一text、int/integer、float/double、blob。存储上所有 auxiliary 值统一落在单张_auxiliary影子表里VEC0_SHADOW_AUXILIARY_NAME查询时通过vec0_get_auxiliary_value_for_rowid按 rowid 读取——这也是它能高效按行取回、却无法参与向量过滤的原因。从 tests/test-auxiliary.py 可以看到auxiliary 列的类型同样严格插入not int、not float、错误类型的 text 或 blob 都会失败并回滚事务而NULL 值完全允许该测试文件还覆盖了 auxiliary 列的 UPDATE 与 DELETE 路径tests/test-auxiliary.py说明 auxiliary 列支持常规的增删改操作。三种列如何选型一张决策图综合官方文档与源码实现选型时可以遵循以下判断该字段需要参与 KNN 的WHERE过滤等于、区间、比较吗需要 →metadata 列。记得只使用/!////布尔列仅用/!并留意 16 列上限。该字段是高频等值过滤键、且每个键值背后有足够多的向量吗是 →partition key 列。它能在物理上把向量聚簇让选择性查询快得多但请保证每个唯一键值约数百个向量避免过度分片并注意 4 列上限与不支持 UPDATE 分区键的限制。该字段只需要随结果取回、从不参与过滤且内容偏大长文本、URL、BLOB是 →auxiliary 列。用前缀声明直接省掉外部表JOIN同样有 16 列上限。这三种列可以共存于同一张vec0表如开头的vec_chunks示例sqlite-vec 会在构造期按向量列 → 分区键列 → 主键列 → auxiliary 列 → metadata 列的顺序逐一解析sqlite-vec.c因此你可以在一条CREATE VIRTUAL TABLE中自由组合它们。完整的语法与 KNN 查询范式还可以继续参考 site/features/knn.md 与 site/api-reference.md深入的表结构设计文档见 ARCHITECTURE.md。小结vec0虚拟表通过 metadata、partition key、auxiliary 三种列把向量检索与业务数据存取优雅地统一到了同一张 SQL 表里metadata 列让 KNN 查询自带过滤、partition key 列让多租户等场景的检索量级骤减、auxiliary 列则省掉了繁琐的JOIN。理解三者的声明语法、类型限制、操作符边界与底层存储差异是设计出既快又稳的 sqlite-vec 表结构的关键一步而把握每个分区键数百向量与过滤走 metadata、取回走 auxiliary这两条原则就能在绝大多数 RAG 与向量搜索场景中做出正确的选择。赞分享向量数据库数据库【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址https://gitcode.com/GitHub_Trending/sq/sqlite-vec点击查看免费下载相关推荐Awesome Scriptable完全指南打造个性化iOS桌面的终极JavaScript工具集Awesome Scriptable完全指南打造个性化iOS桌面的终极JavaScript工具集 Awesome Scriptable 是一个精心策划的Scr文档教程SQLite-Vec终极指南向量搜索与元数据过滤的完美实践SQLite Vec终极指南向量搜索与元数据过滤的完美实践 SQLite Vec是一个革命性的向量搜索SQLite扩展它能够在任何SQLite运行的环境中提向量数据库数据库Flutter应用集成SQLite向量搜索Dart调用sqlite-vec完整指南Flutter应用集成SQLite向量搜索Dart调用sqlite vec完整指南 在现代移动应用开发中向量搜索技术正成为构建智能应用的关键能力。sqlit向量数据库数据库上一篇2026夏季技术实习终极指南3分钟掌握1861个实习机会下一篇终极解决方案3步实现微信QQ防撤回让重要消息不再消失创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考