schema-builder

Convex Schema Builder

用途

schema-builder 用于按照最佳实践构建结构良好的 Convex schema，覆盖表间关系、索引与校验器。它适用于以下场景：

• 创建新的 convex/schema.ts 文件
• 向已有 schema 添加表
• 设计数据模型关系
• 添加或优化索引
• 将嵌套数据转换为关系型结构

Schema 设计原则

• 文档-关系型：使用扁平文档与 ID 引用，避免深层嵌套。
• 为外键建索引：始终为用于查找的字段建索引（如 userId、teamId 等）。
• 限制数组：数组只用于小型、有界集合（少于 8192 项）。
• 类型安全：使用严格的 v.* 类型校验器。

Schema 模板

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tableName: defineTable({
    // Required fields
    field: v.string(),

    // Optional fields
    optional: v.optional(v.number()),

    // Relations (use IDs)
    userId: v.id("users"),

    // Enums with union + literal
    status: v.union(
      v.literal("active"),
      v.literal("pending"),
      v.literal("archived")
    ),

    // Timestamps
    createdAt: v.number(),
    updatedAt: v.optional(v.number()),
  })
    // Index for queries by this field
    .index("by_user", ["userId"])
    // Compound index for common query patterns
    .index("by_user_and_status", ["userId", "status"])
    // Index for time-based queries
    .index("by_created", ["createdAt"]),
});

常见模式

一对多关系

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
  }).index("by_email", ["email"]),

  posts: defineTable({
    userId: v.id("users"),
    title: v.string(),
    content: v.string(),
  }).index("by_user", ["userId"]),
});

多对多（连接表）

export default defineSchema({
  users: defineTable({
    name: v.string(),
  }),

  projects: defineTable({
    name: v.string(),
  }),

  projectMembers: defineTable({
    userId: v.id("users"),
    projectId: v.id("projects"),
    role: v.union(v.literal("owner"), v.literal("member")),
  })
    .index("by_user", ["userId"])
    .index("by_project", ["projectId"])
    .index("by_project_and_user", ["projectId", "userId"]),
});

层级数据

export default defineSchema({
  comments: defineTable({
    postId: v.id("posts"),
    parentId: v.optional(v.id("comments")), // null for top-level
    userId: v.id("users"),
    text: v.string(),
  })
    .index("by_post", ["postId"])
    .index("by_parent", ["parentId"]),
});

小型有界数组（可以使用）

export default defineSchema({
  users: defineTable({
    name: v.string(),
    // Small, bounded collections are fine
    roles: v.array(v.union(
      v.literal("admin"),
      v.literal("editor"),
      v.literal("viewer")
    )),
    tags: v.array(v.string()), // e.g., max 10 tags
  }),
});

校验器参考

// Primitives
v.string()
v.number()
v.boolean()
v.null()
v.id("tableName")

// Optional
v.optional(v.string())

// Union types (enums)
v.union(v.literal("a"), v.literal("b"))

// Objects
v.object({
  key: v.string(),
  nested: v.number(),
})

// Arrays
v.array(v.string())

// Records (arbitrary keys)
v.record(v.string(), v.boolean())

// Any (avoid if possible)
v.any()

索引策略

• 单字段索引：用于简单查找，如 by_user: ["userId"]、by_email: ["email"]。
• 复合索引：用于带过滤的查询，如 by_user_and_status: ["userId", "status"]、by_team_and_created: ["teamId", "createdAt"]。
• 去除冗余：by_a_and_b 通常已覆盖 by_a。

检查清单

• 所有外键都有索引
• 常见查询模式有复合索引
• 数组小型且有界（或已转换为关系）
• 所有字段都有正确的校验器
• 枚举使用 v.union(v.literal(...)) 模式
• 时间戳使用 v.number()（自 epoch 起的毫秒数）

从嵌套结构迁移到关系型

转换前：

users: defineTable({
  posts: v.array(v.object({
    title: v.string(),
    comments: v.array(v.object({ text: v.string() })),
  })),
})

转换后：

users: defineTable({
  name: v.string(),
}),

posts: defineTable({
  userId: v.id("users"),
  title: v.string(),
}).index("by_user", ["userId"]),

comments: defineTable({
  postId: v.id("posts"),
  text: v.string(),
}).index("by_post", ["postId"]),

使用方式与限制

该技能以指导文档和示例模板的形式提供 schema 设计与生成参考，供在 Convex 项目中创建或修改 schema 时遵循。资料未提供具体的安装命令、命令行调用方式、收费信息或运行平台要求，相关事实暂未提供。