用途:生成并维护 Convex 的 convex/schema.ts,为每个文档提供类型、为每条查询路径建立索引,并通过数据库中已有数据的校验。核心规则:函数里每个 withIndex 都要在 schema 中有同名 .index(),索引按字段命名、查询按字段顺序。
主要能力:用 defineSchema 与 defineTable 定义表;字段校验器包括 v.string、v.number、v.boolean、v.null、v.int64、v.bytes、v.id("table")、v.array、v.object、v.record、v.union、v.literal、v.optional、v.any。区分 v.optional(键可缺失)与 v.union(t, v.null())(键存在可为 null)。多形态文档用 v.union 的 v.object 成员做可辨识联合,判别字段放索引首位。索引命名如 by_field1_and_field2,查询需等值前缀加至多一个范围;每表最多 32 个索引、每索引 16 字段,by_id 与 by_creation_time 为保留名。关系用子表 v.id("table") 外键加索引,多对多用连接表;仅在数据有界、随父文档一起加载并一起更新时才内嵌。支持 searchIndex 与 vectorIndex,搜索索引用 withSearchIndex,向量搜索仅在 action 中通过 ctx.vectorSearch 运行。
使用方式:在 convex/schema.ts 中默认导出 defineSchema(...);用 npx convex dev 推送并检查 schema 校验错误。
限制与常见错误:withIndex 无匹配索引会导致部署失败;索引名不体现字段易误用;给已有数据的表加必填字段会使旧文档校验失败,应先 v.optional 再回填;父文档内嵌无界对象数组会触及 8192 上限并产生写冲突;v.bigint() 已弃用,用 v.int64();不要声明 _id 与 _creationTime;不要用 v.any() 逃避建模;Date 不是 Convex 值,用毫秒时间戳。官方文档见 https://docs.convex.dev/database/schemas 等链接。