convex-queries

Convex 查询技能

本技能为实现 Convex 查询函数提供专门指导，包括函数定义、注册、调用模式、分页、索引和全文搜索的最佳实践。

何时使用本技能

在以下情况下使用本技能：

• 定义新的查询函数以从 Convex 数据库获取数据
• 为大型结果集实现分页
• 为高效查询设置索引
• 使用全文搜索功能
• 从其他 Convex 函数调用查询
• 优化查询性能

技能资源

本技能在 references/query-guidelines.md 中包含全面的参考文档，涵盖：

核心查询开发

• 使用新函数语法的函数定义语法
• 查询注册（query 和 internalQuery）
• 参数校验器及其用法
• 函数调用模式（ctx.runQuery）
• 函数引用（api 和 internal 对象）
• 查询路径的基于文件的路由

查询优化

• 查询准则（避免使用 filter，配合 withIndex 使用索引）
• 使用 .order('asc') 和 .order('desc') 对结果排序
• 使用 .unique() 获取单个文档
• 使用 for await 语法进行异步迭代
• 查询限制与性能注意事项

高级查询功能

• 分页：使用 paginationOptsValidator 实现分页查询
  • 理解 paginationOpts（numItems 和 cursor）
  • 读取分页结果（page、isDone、continueCursor）
• 全文搜索：设置并查询搜索索引
• 索引：创建并使用索引以实现高效查找
  • 内置索引（by_id、by_creation_time）
  • 自定义索引命名与字段排序
  • 使用多个索引的嵌套查询

数据库查询

• 使用 ctx.db.query() 从 Convex 数据库读取数据
• 通过 .withIndex() 使用索引
• 使用 .collect() 和 .take(n) 收集结果

如何使用本技能

1. 阅读参考文档 references/query-guidelines.md，了解完整的查询模式
2. 遵循语法示例，使用正确的校验器定义查询函数
3. 使用索引进行高效过滤，而非使用 filter 方法
4. 实现分页以处理大型数据集
5. 利用全文搜索满足基于文本的过滤需求
6. 优化排序，理解 Convex 如何对结果排序

关键查询准则

• 务必为所有查询函数包含参数校验器
• 不要在查询中使用 filter；改用 withIndex
• 使用 ctx.runQuery 从 mutation 或 action 中调用查询
• 在同一文件中调用查询时指定返回类型注解（TypeScript 循环引用变通方案）
• 查询的执行时间最长为 1 秒，最多可读取 16384 个文档
• 如果你的查询没有显式返回值，则隐式返回 null

示例：使用索引的基础查询

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

export const getMessagesByChannel = query({
  args: {
    channelId: v.id("channels"),
  },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
      .order("desc")
      .take(20);
  },
});

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