Convex Schema Validator

Convex でデータベーススキーマを定義・検証し、適切な型指定、インデックス設定、オプショナルフィールド、Union型、スキーマ変更戦略を実装します。

ドキュメンテーションソース

実装前に推測しないでください。最新のドキュメンテーションを取得してください:

• Primary: https://docs.convex.dev/database/schemas
• Indexes: https://docs.convex.dev/database/indexes
• Data Types: https://docs.convex.dev/database/types
• 広い背景: https://docs.convex.dev/llms.txt

手引き

基本的なスキーマ定義

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

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
    avatarUrl: v.optional(v.string()),
    createdAt: v.number(),
  }),
  
  tasks: defineTable({
    title: v.string(),
    description: v.optional(v.string()),
    completed: v.boolean(),
    userId: v.id("users"),
    priority: v.union(
      v.literal("low"),
      v.literal("medium"),
      v.literal("high")
    ),
  }),
});

バリデータタイプ

バリデータ	TypeScript型	例
v.string()	string	"hello"
v.number()	number	42, 3.14
v.boolean()	boolean	true, false
v.null()	null	null
v.int64()	bigint	9007199254740993n
v.bytes()	ArrayBuffer	バイナリデータ
v.id("table")	Id<"table">	ドキュメント参照
v.array(v)	T[]	[1, 2, 3]
v.object({})	{ ... }	{ name: "..." }
v.optional(v)	T | undefined	オプショナルフィールド
v.union(...)	T1 | T2	複数の型
v.literal(x)	"x"	固定値
v.any()	any	すべての値
v.record(k, v)	Record<K, V>	動的キー

インデックス設定

export default defineSchema({
  messages: defineTable({
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
    sentAt: v.number(),
  })
    // 単一フィールドインデックス
    .index("by_channel", ["channelId"])
    // 複合インデックス
    .index("by_channel_and_author", ["channelId", "authorId"])
    // ソート用インデックス
    .index("by_channel_and_time", ["channelId", "sentAt"]),
    
  // フルテキスト検索インデックス
  articles: defineTable({
    title: v.string(),
    body: v.string(),
    category: v.string(),
  })
    .searchIndex("search_content", {
      searchField: "body",
      filterFields: ["category"],
    }),
});

複雑な型

export default defineSchema({
  // ネストされたオブジェクト
  profiles: defineTable({
    userId: v.id("users"),
    settings: v.object({
      theme: v.union(v.literal("light"), v.literal("dark")),
      notifications: v.object({
        email: v.boolean(),
        push: v.boolean(),
      }),
    }),
  }),

  // オブジェクトの配列
  orders: defineTable({
    customerId: v.id("users"),
    items: v.array(v.object({
      productId: v.id("products"),
      quantity: v.number(),
      price: v.number(),
    })),
    status: v.union(
      v.literal("pending"),
      v.literal("processing"),
      v.literal("shipped"),
      v.literal("delivered")
    ),
  }),

  // 動的キー用のレコード型
  analytics: defineTable({
    date: v.string(),
    metrics: v.record(v.string(), v.number()),
  }),
});

判別Union

export default defineSchema({
  events: defineTable(
    v.union(
      v.object({
        type: v.literal("user_signup"),
        userId: v.id("users"),
        email: v.string(),
      }),
      v.object({
        type: v.literal("purchase"),
        userId: v.id("users"),
        orderId: v.id("orders"),
        amount: v.number(),
      }),
      v.object({
        type: v.literal("page_view"),
        sessionId: v.string(),
        path: v.string(),
      })
    )
  ).index("by_type", ["type"]),
});

オプショナルフィールド vs Nullableフィールド

export default defineSchema({
  items: defineTable({
    // オプショナル: フィールドが存在しないかもしれない
    description: v.optional(v.string()),
    
    // Nullable: フィールドが存在するが null の可能性がある
    deletedAt: v.union(v.number(), v.null()),
    
    // オプショナルかつ Nullable
    notes: v.optional(v.union(v.string(), v.null())),
  }),
});

インデックス命名規則

インデックス名には常にインデックス対象のすべてのフィールドを含めます:

export default defineSchema({
  posts: defineTable({
    authorId: v.id("users"),
    categoryId: v.id("categories"),
    publishedAt: v.number(),
    status: v.string(),
  })
    // 良い: 説明的な名前
    .index("by_author", ["authorId"])
    .index("by_author_and_category", ["authorId", "categoryId"])
    .index("by_category_and_status", ["categoryId", "status"])
    .index("by_status_and_published", ["status", "publishedAt"]),
});

スキーママイグレーション戦略

新しいフィールドの追加

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

// After - 最初はオプショナルで追加
users: defineTable({
  name: v.string(),
  email: v.string(),
  avatarUrl: v.optional(v.string()), // 新規オプショナルフィールド
})

データの逆入力

// convex/migrations.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";

export const backfillAvatars = internalMutation({
  args: {},
  returns: v.number(),
  handler: async (ctx) => {
    const users = await ctx.db
      .query("users")
      .filter((q) => q.eq(q.field("avatarUrl"), undefined))
      .take(100);

    for (const user of users) {
      await ctx.db.patch(user._id, {
        avatarUrl: `https://api.dicebear.com/7.x/initials/svg?seed=${user.name}`,
      });
    }

    return users.length;
  },
});

オプショナルフィールドを必須にする

// Step 1: すべての null 値を逆入力
// Step 2: スキーマを必須に更新
users: defineTable({
  name: v.string(),
  email: v.string(),
  avatarUrl: v.string(), // 逆入力後は必須
})

例

完全な Eコマーススキーマ

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

export default defineSchema({
  users: defineTable({
    email: v.string(),
    name: v.string(),
    role: v.union(v.literal("customer"), v.literal("admin")),
    createdAt: v.number(),
  })
    .index("by_email", ["email"])
    .index("by_role", ["role"]),

  products: defineTable({
    name: v.string(),
    description: v.string(),
    price: v.number(),
    category: v.string(),
    inventory: v.number(),
    isActive: v.boolean(),
  })
    .index("by_category", ["category"])
    .index("by_active_and_category", ["isActive", "category"])
    .searchIndex("search_products", {
      searchField: "name",
      filterFields: ["category", "isActive"],
    }),

  orders: defineTable({
    userId: v.id("users"),
    items: v.array(v.object({
      productId: v.id("products"),
      quantity: v.number(),
      priceAtPurchase: v.number(),
    })),
    total: v.number(),
    status: v.union(
      v.literal("pending"),
      v.literal("paid"),
      v.literal("shipped"),
      v.literal("delivered"),
      v.literal("cancelled")
    ),
    shippingAddress: v.object({
      street: v.string(),
      city: v.string(),
      state: v.string(),
      zip: v.string(),
      country: v.string(),
    }),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_status", ["userId", "status"])
    .index("by_status", ["status"]),

  reviews: defineTable({
    productId: v.id("products"),
    userId: v.id("users"),
    rating: v.number(),
    comment: v.optional(v.string()),
    createdAt: v.number(),
  })
    .index("by_product", ["productId"])
    .index("by_user", ["userId"]),
});

関数でのスキーマ型の使用

// convex/products.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { Doc, Id } from "./_generated/dataModel";

// 完全なドキュメント用に Doc 型を使用
type Product = Doc<"products">;

// 参照用に Id 型を使用
type ProductId = Id<"products">;

export const get = query({
  args: { productId: v.id("products") },
  returns: v.union(
    v.object({
      _id: v.id("products"),
      _creationTime: v.number(),
      name: v.string(),
      description: v.string(),
      price: v.number(),
      category: v.string(),
      inventory: v.number(),
      isActive: v.boolean(),
    }),
    v.null()
  ),
  handler: async (ctx, args): Promise<Product | null> => {
    return await ctx.db.get(args.productId);
  },
});

ベストプラクティス

• 明示的に指示されない限り npx convex deploy を実行しない
• 明示的に指示されない限りどんな git コマンドも実行しない
• 推論に頼るのではなく、常に明示的なスキーマを定義する
• インデックス済みのすべてのフィールドを含むわかりやすいインデックス名を使用する
• 新しい列を追加する場合は、最初はオプショナルフィールドから始める
• ポリモーフィックデータには判別Union を使用する
• 関数だけではなく、スキーマレベルでデータを検証する
• クエリパターンに基づいてインデックス戦略を計画する

よくある落とし穴

1. クエリ用インデックスの欠落 - すべての withIndex には対応するスキーマインデックスが必要
2. インデックスフィールド順序の誤り - フィールドは定義された順序でクエリされる必要がある
3. v.any() の過度な使用 - 型安全性のメリットが失われる
4. 新規フィールドを必須にするのを忘れる - 既存データが破損する
5. システムフィールドを忘れる - _id と _creationTime は自動的に付与される

参考資料

• Convex Documentation: https://docs.convex.dev/
• Convex LLMs.txt: https://docs.convex.dev/llms.txt
• Schemas: https://docs.convex.dev/database/schemas
• Indexes: https://docs.convex.dev/database/indexes
• Data Types: https://docs.convex.dev/database/types