convex-performance-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Performance Audit

Convex 性能审计

Diagnose and fix performance problems in Convex applications, one problem class at a time.

逐一诊断并修复Convex应用中的性能问题。

When to Use

适用场景

A Convex page or feature feels slow or expensive
```
npx convex insights --details
```
reports high bytes read, documents read, or OCC conflicts
Low-freshness read paths are using reactivity where point-in-time reads would do
OCC conflict errors or excessive mutation retries
High subscription count or slow UI updates
Functions approaching execution or transaction limits
The same performance pattern needs fixing across sibling functions

Convex页面或功能运行缓慢或成本过高
```
npx convex insights --details
```
报告显示读取字节数、读取文档数或OCC冲突量较高
低实时性读取路径在可使用时点读取的场景下使用了响应式机制
出现OCC冲突错误或过度的突变重试
订阅数量过高或UI更新缓慢
函数即将达到执行或事务限制
多个同类函数存在相同的性能问题需要修复

When Not to Use

不适用场景

Initial Convex setup, auth setup, or component extraction
Pure schema migrations with no performance goal
One-off micro-optimizations without a user-visible or deployment-visible problem

Convex初始设置、认证设置或组件提取
无性能优化目标的纯Schema迁移
无用户可见或部署层面可见问题的一次性微优化

Guardrails

注意准则

Prefer simpler code when scale is small, traffic is modest, or the available signals are weak
Do not recommend digest tables, document splitting, fetch-strategy changes, or migration-heavy rollouts unless there is a measured signal, a clearly unbounded path, or a known hot read/write path
In Convex, a simple scan on a small table is often acceptable. Do not invent structural work just because a pattern is not ideal at large scale

在规模较小、流量适中或可用信号不足时，优先选择更简洁的代码
除非有可量化的信号、明确的无界路径或已知的热点读/写路径，否则不建议使用摘要表、文档拆分、获取策略变更或涉及大量迁移的部署方案
在Convex中，对小型表执行简单扫描通常是可接受的。不要仅仅因为某种模式在大规模场景下不够理想就进行结构性改造

First Step: Gather Signals

第一步：收集数据信号

Start with the strongest signal available:

If deployment Health insights are already available from the user or the current context, treat them as a first-class source of performance signals.
If CLI insights are available, run
```
npx convex insights --details
```
. Use
```
--prod
```
,
```
--preview-name
```
, or
```
--deployment-name
```
when needed.
- If the local repo's Convex CLI is too old to support
```
insights
```
  , try
```
npx -y convex@latest insights --details
```
  before giving up.
If the repo already uses
```
convex-doctor
```
, you may treat its findings as hints. Do not require it, and do not treat it as the source of truth.
If runtime signals are unavailable, audit from code anyway, but keep the guardrails above in mind. Lack of insights is not proof of health, but it is also not proof that a large refactor is warranted.

从最可靠的可用信号开始：

如果用户或当前环境已提供部署健康洞察数据，将其作为首要的性能信号来源。
如果可以使用CLI洞察工具，运行
```
npx convex insights --details
```
。必要时使用
```
--prod
```
、
```
--preview-name
```
或
```
--deployment-name
```
参数。
- 如果本地仓库的Convex CLI版本过旧不支持
```
insights
```
  命令，先尝试运行
```
npx -y convex@latest insights --details
```
  再考虑放弃。
如果仓库已使用
```
convex-doctor
```
，可将其结果作为参考，但不强制要求，也不将其视为绝对权威。
如果无法获取运行时信号，仍可通过代码审计进行检查，但需牢记上述注意准则。缺乏洞察数据不代表系统健康，也不意味着需要进行大规模重构。

Signal Routing

信号匹配

After gathering signals, identify the problem class and read the matching reference file.

Signal	Reference
High bytes or documents read, JS filtering, unnecessary joins	`references/hot-path-rules.md`
OCC conflict errors, write contention, mutation retries	`references/occ-conflicts.md`
High subscription count, slow UI updates, excessive re-renders	`references/subscription-cost.md`
Function timeouts, transaction size errors, large payloads	`references/function-budget.md`
General "it's slow" with no specific signal	Start with `references/hot-path-rules.md`

Multiple problem classes can overlap. Read the most relevant reference first, then check the others if symptoms remain.

收集信号后，确定问题类别并阅读对应的参考文档。

信号	参考文档
读取字节数或文档数过高、JS端过滤、不必要的关联查询	`references/hot-path-rules.md`
OCC冲突错误、写入冲突、突变重试	`references/occ-conflicts.md`
订阅数量过高、UI更新缓慢、过度重渲染	`references/subscription-cost.md`
函数超时、事务大小错误、大负载	`references/function-budget.md`
仅反馈“运行缓慢”无具体信号	从 `references/hot-path-rules.md` 开始排查

多个问题类别可能存在重叠。先阅读最相关的参考文档，若症状仍存在，再检查其他文档。

Escalate Larger Fixes

重大修复需确认

If the likely fix is invasive, cross-cutting, or migration-heavy, stop and present options before editing.

Examples:

introducing digest or summary tables across multiple flows
splitting documents to isolate frequently-updated fields
reworking pagination or fetch strategy across several screens
switching to a new index or denormalized field that needs migration-safe rollout

When correctness depends on handling old and new states during a rollout, consult

skills/convex-migration-helper/SKILL.md

for the migration workflow.

如果可能的修复方案具有侵入性、跨模块或涉及大量迁移，需先停止操作并给出可选方案，再进行编辑。

示例：

在多个流程中引入摘要表或汇总表
拆分文档以隔离频繁更新的字段
重写多个页面的分页或获取策略
切换到需要迁移安全部署的新索引或非规范化字段

当正确性依赖于部署过程中对新旧状态的处理时，请参考

skills/convex-migration-helper/SKILL.md

中的迁移流程。

Workflow

工作流程

1. Scope the problem

1. 界定问题范围

Pick one concrete user flow from the actual project. Look at the codebase, client pages, and API surface to find the flow that matches the symptom.

Write down:

entrypoint functions
client callsites using
```
useQuery
```
,
```
usePaginatedQuery
```
, or
```
useMutation
```
tables read
tables written
whether the path is high-read, high-write, or both

从实际项目中选取一个具体的用户流程。查看代码库、客户端页面和API接口，找到与症状匹配的流程。

记录：

入口函数
使用
```
useQuery
```
、
```
usePaginatedQuery
```
或
```
useMutation
```
的客户端调用点
读取的表
写入的表
该路径属于高读取、高写入还是两者兼具

2. Trace the full read and write set

2. 追踪完整的读写集合

For each function in the path:

Trace every
```
ctx.db.get()
```
and
```
ctx.db.query()
```

Trace every

ctx.db.patch()

ctx.db.replace()

, and

ctx.db.insert()

Note foreign-key lookups, JS-side filtering, and full-document reads
Identify all sibling functions touching the same tables
Identify reactive stats, aggregates, or widgets rendered on the same page

In Convex, every extra read increases transaction work, and every write can invalidate reactive subscribers. Treat read amplification and invalidation amplification as first-class problems.

针对路径中的每个函数：

追踪所有
```
ctx.db.get()
```
和
```
ctx.db.query()
```
操作

追踪所有

ctx.db.patch()

、

ctx.db.replace()

和

ctx.db.insert()

操作

记录外键查找、JS端过滤和全文档读取操作
识别所有访问相同表的同类函数
识别同一页面上渲染的响应式统计数据、聚合结果或组件

在Convex中，每一次额外的读取都会增加事务负载，每一次写入都可能使响应式订阅失效。需将读取放大和失效放大视为核心问题。

3. Apply fixes from the relevant reference

3. 应用对应参考文档中的修复方案

Read the reference file matching your problem class. Each reference includes specific patterns, code examples, and a recommended fix order.

Do not stop at the single function named by an insight. Trace sibling readers and writers touching the same tables.

阅读与问题类别匹配的参考文档。每个参考文档都包含具体模式、代码示例和推荐的修复顺序。

不要仅停留在洞察数据指出的单个函数上。需追踪访问相同表的同类读取和写入函数。

4. Fix sibling functions together

4. 统一修复同类函数

When one function touching a table has a performance bug, audit sibling functions for the same pattern.

After finding one problem, inspect both sibling readers and sibling writers for the same table family, including companion digest or summary tables.

Examples:

If one list query switches from full docs to a digest table, inspect the other list queries for that table
If one mutation needs no-op write protection, inspect the other writers to the same table
If one read path needs a migration-safe rollout for an unbackfilled field, inspect sibling reads for the same rollout risk

Do not leave one path fixed and another path on the old pattern unless there is a clear product reason.

当某个访问表的函数存在性能问题时，需审计同类函数是否存在相同模式。

发现一个问题后，检查同一表族的所有同类读取和写入函数，包括配套的摘要表或汇总表。

示例：

如果某个列表查询从全文档读取切换为摘要表读取，检查该表的其他列表查询
如果某个突变需要无操作写入保护，检查同一表的其他写入函数
如果某个读取路径对未回填字段需要迁移安全部署，检查同类读取是否存在相同的部署风险

除非有明确的产品原因，否则不要仅修复一个路径而保留其他路径的旧模式。

5. Verify before finishing

5. 完成前验证

Confirm all of these:

Results are the same as before, no dropped records
Eliminated reads or writes are no longer in the path where expected
Fallback behavior works when denormalized or indexed fields are missing
New writes avoid unnecessary invalidation when data is unchanged
Every relevant sibling reader and writer was inspected, not just the original function

确认以下所有事项：

结果与修复前一致，无记录丢失
预期路径中的多余读取或写入已被消除
当非规范化或索引字段缺失时，回退行为正常
新的写入操作在数据未变更时避免不必要的失效
已检查所有相关的同类读取和写入函数，而非仅原函数

Reference Files

参考文档

```
references/hot-path-rules.md
```
- Read amplification, invalidation, denormalization, indexes, digest tables
```
references/occ-conflicts.md
```
- Write contention, OCC resolution, hot document splitting
```
references/subscription-cost.md
```
- Reactive query cost, subscription granularity, point-in-time reads
```
references/function-budget.md
```
- Execution limits, transaction size, large documents, payload size

Also check the official Convex Best Practices page for additional patterns covering argument validation, access control, and code organization that may surface during the audit.

```
references/hot-path-rules.md
```
- 读取放大、失效、非规范化、索引、摘要表
```
references/occ-conflicts.md
```
- 写入冲突、OCC解决、热点文档拆分
```
references/subscription-cost.md
```
- 响应式查询成本、订阅粒度、时点读取
```
references/function-budget.md
```
- 执行限制、事务大小、大文档、负载大小

同时可查看官方的Convex最佳实践页面，获取审计过程中可能涉及的参数验证、访问控制和代码组织等额外模式。