convex-mutations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Mutations Skill

Convex Mutations 技能指南

This skill provides specialized guidance for implementing Convex mutation functions, including best practices for function definition, registration, database operations, and scheduling patterns.

本技能为实现Convex mutation函数提供专业指导，涵盖函数定义、注册、数据库操作和调度模式的最佳实践。

When to Use This Skill

适用场景

Use this skill when:

Defining new mutation functions to write or modify data in the Convex database
Performing database operations (
```
insert
```
,
```
patch
```
,
```
replace
```
,
```
delete
```
)
Calling mutations from other Convex functions
Scheduling future mutations with
```
ctx.scheduler.runAfter
```
Handling transactional operations
Coordinating mutations with actions for background processing

使用本技能的场景包括：

定义新的mutation函数以在Convex数据库中写入或修改数据
执行数据库操作（
```
insert
```
、
```
patch
```
、
```
replace
```
、
```
delete
```
）
从其他Convex函数中调用mutation
使用
```
ctx.scheduler.runAfter
```
调度未来执行的mutation
处理事务操作
协调mutation与action以实现后台处理

Skill Resources

技能相关资源

This skill includes comprehensive reference documentation in

references/mutation-guidelines.md

that covers:

本技能包含位于

references/mutation-guidelines.md

中的完整参考文档，涵盖以下内容：

Core Mutation Development

核心Mutation开发

Function definition syntax using the new function syntax
Mutation registration (
```
mutation
```
and
```
internalMutation
```
)
Argument validators and their usage
Function calling patterns (
```
ctx.runQuery
```
and
```
ctx.runMutation
```
)
Function references (
```
api
```
and
```
internal
```
objects)
File-based routing for mutation paths

使用新函数语法的函数定义格式
Mutation注册（
```
mutation
```
和
```
internalMutation
```
）
参数验证器及其使用方法
函数调用模式（
```
ctx.runQuery
```
和
```
ctx.runMutation
```
）
函数引用（
```
api
```
和
```
internal
```
对象）
基于文件的mutation路径路由

Database Operations

数据库操作

```
ctx.db.insert()
```
- Create new documents
```
ctx.db.patch()
```
- Shallow merge updates into existing documents
```
ctx.db.replace()
```
- Fully replace existing documents
Error handling for missing documents
Transaction semantics and consistency guarantees

```
ctx.db.insert()
```
- 创建新文档
```
ctx.db.patch()
```
- 对现有文档进行浅合并更新
```
ctx.db.replace()
```
- 完全替换现有文档
缺失文档的错误处理
事务语义与一致性保障

Advanced Mutation Features

Mutation高级特性

Scheduling: Using
```
ctx.scheduler.runAfter()
```
to queue background jobs
- Scheduling mutations and actions for future execution
- Understanding that auth state does NOT propagate to scheduled jobs
- Using internal functions for scheduled jobs that need privileges
- Avoiding tight loops and respecting 10-second minimum intervals
Transactional Behavior: Understanding mutation transactions
- Enqueuing scheduler jobs is transactional within mutations
- Race condition prevention through transaction boundaries

调度：使用
```
ctx.scheduler.runAfter()
```
将后台任务加入队列
- 调度mutation和action在未来执行
- 注意：认证状态不会传递给定时任务
- 对需要权限的定时任务使用内部函数
- 避免死循环，遵守至少10秒的间隔要求
事务行为：理解mutation事务
- 在mutation中加入调度队列的操作是事务性的
- 通过事务边界防止竞态条件

Function Composition

函数组合

Calling queries within mutations for validation
Calling mutations from mutations
Using return type annotations for same-file mutation calls

在mutation中调用query进行验证
从mutation中调用其他mutation
对同文件内的mutation调用使用返回类型注解

How to Use This Skill

如何使用本技能

Read the reference documentation at
```
references/mutation-guidelines.md
```
to understand the complete mutation patterns
Follow the syntax examples for defining mutation functions with proper validators
Use appropriate database operations (
```
insert
```
,
```
patch
```
,
```
replace
```
) based on your needs
Schedule background work using
```
ctx.scheduler.runAfter
```
for long-running operations
Remember auth state does NOT propagate to scheduled jobs; use internal functions for privileged operations
Leverage transactions for consistency across multiple operations

阅读参考文档：查看
```
references/mutation-guidelines.md
```
以了解完整的mutation模式
遵循语法示例：使用正确的验证器定义mutation函数
选择合适的数据库操作：根据需求使用
```
insert
```
、
```
patch
```
、
```
replace
```
调度后台任务：对长时间运行的操作使用
```
ctx.scheduler.runAfter
```
注意认证状态不传递：定时任务不会继承认证状态，对需要权限的操作使用内部函数
利用事务：确保多操作之间的一致性

Key Mutation Guidelines

Mutation核心准则

ALWAYS include argument validators for all mutation functions
Use
```
ctx.db.patch()
```
for partial updates and
```
ctx.db.replace()
```
for full replacements
Use
```
ctx.scheduler.runAfter()
```
to schedule actions (e.g., AI responses, notifications)
Remember that scheduled jobs have
```
null
```
auth state; use internal functions instead
Mutations execute for at most 1 second and can write up to 8192 documents
Return
```
null
```
implicitly if your mutation doesn't have an explicit return value
Use return type annotations when calling mutations in the same file (TypeScript circularity workaround)

所有mutation函数必须包含参数验证器
部分更新使用
```
ctx.db.patch()
```
，完全替换使用
```
ctx.db.replace()
```
使用
```
ctx.scheduler.runAfter()
```
调度action（如AI回复、通知）
注意定时任务的认证状态为
```
null
```
，请使用内部函数替代
Mutation的最长执行时间为1秒，最多可写入8192个文档
如果mutation没有显式返回值，会隐式返回
```
null
```
在同文件内调用mutation时使用返回类型注解（解决TypeScript循环引用问题）

Example: Mutation with Database Operation and Scheduling

示例：包含数据库操作与调度的Mutation

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

export const sendMessage = mutation({
  args: {
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
  },
  handler: async (ctx, args) => {
    // Validate channel and user exist
    const channel = await ctx.db.get(args.channelId);
    if (!channel) {
      throw new Error("Channel not found");
    }

    // Insert message into database
    await ctx.db.insert("messages", {
      channelId: args.channelId,
      authorId: args.authorId,
      content: args.content,
    });

    // Schedule AI response generation (transactional)
    await ctx.scheduler.runAfter(0, internal.functions.generateResponse, {
      channelId: args.channelId,
    });

    return null;
  },
});

export const updateUserStatus = mutation({
  args: {
    userId: v.id("users"),
    status: v.string(),
  },
  handler: async (ctx, args) => {
    // Patch updates an existing document with shallow merge
    await ctx.db.patch(args.userId, {
      status: args.status,
      lastUpdated: Date.now(),
    });
    return null;
  },
});

For more detailed information and additional patterns, refer to the complete reference documentation.

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

export const sendMessage = mutation({
  args: {
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
  },
  handler: async (ctx, args) => {
    // Validate channel and user exist
    const channel = await ctx.db.get(args.channelId);
    if (!channel) {
      throw new Error("Channel not found");
    }

    // Insert message into database
    await ctx.db.insert("messages", {
      channelId: args.channelId,
      authorId: args.authorId,
      content: args.content,
    });

    // Schedule AI response generation (transactional)
    await ctx.scheduler.runAfter(0, internal.functions.generateResponse, {
      channelId: args.channelId,
    });

    return null;
  },
});

export const updateUserStatus = mutation({
  args: {
    userId: v.id("users"),
    status: v.string(),
  },
  handler: async (ctx, args) => {
    // Patch updates an existing document with shallow merge
    await ctx.db.patch(args.userId, {
      status: args.status,
      lastUpdated: Date.now(),
    });
    return null;
  },
});

如需更详细的信息和更多模式，请参考完整的参考文档。