Convex Functions

クエリ、ミューテーション、アクション、HTTP エンドポイントなど、Convex 関数をマスターします。適切な検証、エラーハンドリング、ランタイムに関する考慮事項を備えています。

コード品質

このスキルのすべての例は @convex-dev/eslint-plugin ルールに準拠しています:

• handler プロパティを持つオブジェクト構文
• すべての関数の引数バリデーター
• データベース操作での明示的なテーブル名

linting 設定については、convex-best-practices のコード品質セクションを参照してください。

ドキュメントソース

実装する前に推測しないでください。最新のドキュメントを取得してください:

• Primary: https://docs.convex.dev/functions
• Query Functions: https://docs.convex.dev/functions/query-functions
• Mutation Functions: https://docs.convex.dev/functions/mutation-functions
• Actions: https://docs.convex.dev/functions/actions
• HTTP Actions: https://docs.convex.dev/functions/http-actions
• 広域コンテキスト用: https://docs.convex.dev/llms.txt

指示

関数タイプの概要

タイプ	データベースアクセス	外部 API	キャッシング	ユースケース
Query	読み取り専用	いいえ	はい、リアクティブ	データの取得
Mutation	読み取り/書き込み	いいえ	いいえ	データの変更
Action	runQuery/runMutation 経由	はい	いいえ	外部統合
HTTP Action	runQuery/runMutation 経由	はい	いいえ	Webhook、API

クエリ

クエリはリアクティブで、キャッシュされ、読み取り専用です:

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.union(
    v.object({
      _id: v.id("users"),
      _creationTime: v.number(),
      name: v.string(),
      email: v.string(),
    }),
    v.null(),
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get("users", args.userId);
  },
});

// インデックス付きクエリ
export const listUserTasks = query({
  args: { userId: v.id("users") },
  returns: v.array(
    v.object({
      _id: v.id("tasks"),
      _creationTime: v.number(),
      title: v.string(),
      completed: v.boolean(),
    }),
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .collect();
  },
});

ミューテーション

ミューテーションはデータベースを変更し、トランザクション的です:

import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

export const createTask = mutation({
  args: {
    title: v.string(),
    userId: v.id("users"),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    // ユーザーの存在を検証
    const user = await ctx.db.get("users", args.userId);
    if (!user) {
      throw new ConvexError("User not found");
    }

    return await ctx.db.insert("tasks", {
      title: args.title,
      userId: args.userId,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

export const deleteTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.delete("tasks", args.taskId);
    return null;
  },
});

アクション

アクションは外部 API を呼び出すことができますが、直接的なデータベースアクセスはありません:

"use node";

import { action } from "./_generated/server";
import { v } from "convex/values";
import { api, internal } from "./_generated/api";

export const sendEmail = action({
  args: {
    to: v.string(),
    subject: v.string(),
    body: v.string(),
  },
  returns: v.object({ success: v.boolean() }),
  handler: async (ctx, args) => {
    // 外部 API を呼び出す
    const response = await fetch("https://api.email.com/send", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(args),
    });

    return { success: response.ok };
  },
});

// クエリとミューテーションを呼び出すアクション
export const processOrder = action({
  args: { orderId: v.id("orders") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // クエリ経由でデータを読む
    const order = await ctx.runQuery(api.orders.get, { orderId: args.orderId });

    if (!order) {
      throw new Error("Order not found");
    }

    // 外部決済 API を呼び出す
    const paymentResult = await processPayment(order);

    // ミューテーション経由でデータベースを更新
    await ctx.runMutation(internal.orders.updateStatus, {
      orderId: args.orderId,
      status: paymentResult.success ? "paid" : "failed",
    });

    return null;
  },
});

HTTP アクション

HTTP アクションは Webhook と外部リクエストを処理します:

// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { api, internal } from "./_generated/api";

const http = httpRouter();

// Webhook エンドポイント
http.route({
  path: "/webhooks/stripe",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    const signature = request.headers.get("stripe-signature");
    const body = await request.text();

    // Webhook の署名を検証
    if (!verifyStripeSignature(body, signature)) {
      return new Response("Invalid signature", { status: 401 });
    }

    const event = JSON.parse(body);

    // Webhook を処理
    await ctx.runMutation(internal.payments.handleWebhook, {
      eventType: event.type,
      data: event.data,
    });

    return new Response("OK", { status: 200 });
  }),
});

// API エンドポイント
http.route({
  path: "/api/users/:userId",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    const url = new URL(request.url);
    const userId = url.pathname.split("/").pop();

    const user = await ctx.runQuery(api.users.get, {
      userId: userId as Id<"users">,
    });

    if (!user) {
      return new Response("Not found", { status: 404 });
    }

    return Response.json(user);
  }),
});

export default http;

内部関数

機密操作には内部関数を使用します:

import {
  internalMutation,
  internalQuery,
  internalAction,
} from "./_generated/server";
import { v } from "convex/values";

// 他の Convex 関数からのみ呼び出し可能
export const _updateUserCredits = internalMutation({
  args: {
    userId: v.id("users"),
    amount: v.number(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const user = await ctx.db.get("users", args.userId);
    if (!user) return null;

    await ctx.db.patch("users", args.userId, {
      credits: (user.credits || 0) + args.amount,
    });
    return null;
  },
});

// アクションから内部関数を呼び出す
export const purchaseCredits = action({
  args: { userId: v.id("users"), amount: v.number() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // 外部で決済を処理
    await processPayment(args.amount);

    // 内部ミューテーション経由でクレジットを更新
    await ctx.runMutation(internal.users._updateUserCredits, {
      userId: args.userId,
      amount: args.amount,
    });

    return null;
  },
});

スケジューリング関数

関数を後で実行するようにスケジュール設定します:

import { mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const scheduleReminder = mutation({
  args: {
    userId: v.id("users"),
    message: v.string(),
    delayMs: v.number(),
  },
  returns: v.id("_scheduled_functions"),
  handler: async (ctx, args) => {
    return await ctx.scheduler.runAfter(
      args.delayMs,
      internal.notifications.sendReminder,
      { userId: args.userId, message: args.message },
    );
  },
});

export const sendReminder = internalMutation({
  args: {
    userId: v.id("users"),
    message: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      sentAt: Date.now(),
    });
    return null;
  },
});

例

完全な関数ファイル

// convex/messages.ts
import { query, mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";
import { internal } from "./_generated/api";

const messageValidator = v.object({
  _id: v.id("messages"),
  _creationTime: v.number(),
  channelId: v.id("channels"),
  authorId: v.id("users"),
  content: v.string(),
  editedAt: v.optional(v.number()),
});

// 公開クエリ
export const list = query({
  args: {
    channelId: v.id("channels"),
    limit: v.optional(v.number()),
  },
  returns: v.array(messageValidator),
  handler: async (ctx, args) => {
    const limit = args.limit ?? 50;
    return await ctx.db
      .query("messages")
      .withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
      .order("desc")
      .take(limit);
  },
});

// 公開ミューテーション
export const send = mutation({
  args: {
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
  },
  returns: v.id("messages"),
  handler: async (ctx, args) => {
    if (args.content.trim().length === 0) {
      throw new ConvexError("Message cannot be empty");
    }

    const messageId = await ctx.db.insert("messages", {
      channelId: args.channelId,
      authorId: args.authorId,
      content: args.content.trim(),
    });

    // 通知をスケジュール
    await ctx.scheduler.runAfter(0, internal.messages.notifySubscribers, {
      channelId: args.channelId,
      messageId,
    });

    return messageId;
  },
});

// 内部ミューテーション
export const notifySubscribers = internalMutation({
  args: {
    channelId: v.id("channels"),
    messageId: v.id("messages"),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    // チャネルのサブスクライバーを取得して通知
    const subscribers = await ctx.db
      .query("subscriptions")
      .withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
      .collect();

    for (const sub of subscribers) {
      await ctx.db.insert("notifications", {
        userId: sub.userId,
        messageId: args.messageId,
        read: false,
      });
    }
    return null;
  },
});

ベストプラクティス

• npx convex deploy は明示的に指示されない限り実行しないでください
• 明示的に指示されない限り、git コマンドを実行しないでください
• args と returns バリデーターを常に定義してください
• 読み取り操作にはクエリを使用してください(キャッシュされてリアクティブです)
• 書き込み操作にはミューテーションを使用してください(トランザクション的です)
• 外部 API を呼び出すときだけアクションを使用してください
• 機密操作には内部関数を使用してください
• Node.js API を使用するアクションファイルの先頭に "use node"; を追加してください
• ConvexError でエラーを処理してください(ユーザー向けメッセージ用)

よくある落とし穴

1. データベース操作にアクションを使用する - 代わりにクエリ/ミューテーションを使用してください
2. クエリ/ミューテーションから外部 API を呼び出す - アクションを使用してください
3. "use node" の追加を忘れる - アクション内の Node.js API に必須です
4. return バリデーターが不足している - 常に returns を指定してください
5. 機密ロジックに内部関数を使用していない - internalMutation で保護してください

参考資料

• Convex ドキュメント: https://docs.convex.dev/
• Convex LLMs.txt: https://docs.convex.dev/llms.txt
• Functions Overview: https://docs.convex.dev/functions
• Query Functions: https://docs.convex.dev/functions/query-functions
• Mutation Functions: https://docs.convex.dev/functions/mutation-functions
• Actions: https://docs.convex.dev/functions/actions