用途：在实现 Convex 查询函数时提供规范指引，覆盖函数定义、注册、调用、分页、索引与全文搜索。
主要能力：讲解使用新函数语法定义查询、通过 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()，配合 .withIndex()、.collect() 与 .take(n)。
使用方式：先阅读 references/query-guidelines.md 了解完整模式，再按示例定义带校验器的查询函数，用索引过滤，大数据集用分页，文本过滤用全文搜索。
限制：查询最多执行 1 秒、最多读取 16384 个文档；所有查询函数必须包含参数校验器；不要使用 filter；在同文件调用查询时需指定返回类型注解以规避 TypeScript 循环问题；无显式返回值时隐式返回 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); }, });