convex-backend

Convex バックエンドのガイドライン

読み込むタイミング

• トリガー：Convex に固有の開発、Convex 関数、スキーマ、クエリ、ミューテーション、アクション、リアルタイムサブスクリプションの作成
• スキップ：プロジェクトのバックエンドに Convex を使用していない場合

TypeScript で Convex バックエンドを構築するための包括的なガイドです。関数の構文、バリデーター、スキーマ、クエリ、ミューテーション、アクション、スケジューリング、ファイルストレージについて説明します。

適用するタイミング

以下の場合に、このガイドラインを参照してください。

• 新しい Convex 関数（クエリ、ミューテーション、アクション）を作成するとき
• データベーススキーマとバリデーターを定義するとき
• リアルタイムのデータ取得を実装するとき
• cron ジョブやスケジュールされた関数を設定するとき
• ファイルストレージを扱うとき
• API 構造を設計するとき

ルールのカテゴリ

カテゴリ	影響	説明
関数の構文	CRITICAL	args/returns/handler を使用する新しい関数構文
バリデーター	CRITICAL	型安全な引数と戻り値の検証
スキーマ設計	HIGH	テーブル定義、インデックス、システムフィールド
クエリパターン	HIGH	インデックスを使用した効率的なデータ取得
ミューテーションパターン	MEDIUM	データベースへの書き込み、patch と replace の使い分け
アクションパターン	MEDIUM	外部 API 呼び出し、Node.js ランタイム
スケジューリング	MEDIUM	cron と遅延関数の実行
ファイルストレージ	LOW	Blob ストレージとメタデータ

クイックリファレンス

関数の登録

// Public functions (exposed to clients)
import { query, mutation, action } from "./_generated/server";

// Internal functions (only callable from other Convex functions)
import {
  internalQuery,
  internalMutation,
  internalAction,
} from "./_generated/server";

関数の構文（必ず使用してください）

export const myFunction = query({
  args: { name: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    return "Hello " + args.name;
  },
});

よく使うバリデーター

型	バリデーター	例
文字列	v.string()	"hello"
数値	v.number()	3.14
真偽値	v.boolean()	true
ID	v.id("tableName")	doc._id
配列	v.array(v.string())	["a", "b"]
オブジェクト	v.object({...})	{name: "x"}
オプション	v.optional(v.string())	undefined
ユニオン	v.union(v.string(), v.number())	"x" or 1
リテラル	v.literal("status")	"status"
Null	v.null()	null

関数参照

// Public functions
import { api } from "./_generated/api";
api.example.myQuery; // convex/example.ts → myQuery

// Internal functions
import { internal } from "./_generated/api";
internal.example.myInternalMutation;

インデックスを使ったクエリ

// Schema
messages: defineTable({...}).index("by_channel", ["channelId"])

// Query
await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
  .order("desc")
  .take(10);

重要なルール

1. すべての関数に必ず args と returns のバリデーターを含めてください
2. 戻り値がない場合は v.null() を使用してください - 戻り値のバリデーターを省略してはいけません
3. filter() ではなく withIndex() を使用してください - スキーマでインデックスを定義します
4. プライベート関数には internalQuery/Mutation/Action を使用してください
5. アクションから ctx.db にはアクセスできません - 代わりに runQuery/runMutation を使用してください
6. 同じファイル内で関数を呼び出す場合は型注釈を含めてください

コンパイル済みドキュメント全文

すべてのルールと詳細なコード例を含む完全なガイドについては、AGENTS.md を参照してください。