Convex Schema Builder

Build well-structured Convex schemas following best practices for relationships, indexes, and validators.

When to Use

• Creating a new convex/schema.ts file

• Adding tables to existing schema

• Designing data model relationships

• Adding or optimizing indexes

• Converting nested data to relational structure

Schema Design Principles

• Document-Relational: Use flat documents with ID references, not deep nesting

• Index Foreign Keys: Always index fields used in lookups (userId, teamId, etc.)

• Limit Arrays: Only use arrays for small, bounded collections (<8192 items)

• Type Safety: Use strict validators with v.* types

Schema Template

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"]), });

Common Patterns

One-to-Many Relationship

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"]), });

Many-to-Many with Junction Table

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"]), });

Hierarchical Data

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"]), });

Small Bounded Arrays (OK to use)

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 }), });

Validator Reference

// 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()

Index Strategy

Single-field indexes: For simple lookups

• by_user: ["userId"]

• by_email: ["email"]

Compound indexes: For filtered queries

• by_user_and_status: ["userId", "status"]

• by_team_and_created: ["teamId", "createdAt"]

Remove redundant: by_a_and_b usually covers by_a

Checklist

• All foreign keys have indexes

• Common query patterns have compound indexes

• Arrays are small and bounded (or converted to relations)

• All fields have proper validators

• Enums use v.union(v.literal(...)) pattern

• Timestamps use v.number() (milliseconds since epoch)

Migration from Nested to Relational

If converting from nested structures:

Before:

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

After:

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"]),