convex-queries_skill

Overview

This skill provides practical guidance for implementing Convex query functions. It covers defining and registering queries, calling patterns, pagination, full text search, and index strategies to keep queries efficient and predictable. Use it to standardize query behavior and optimize read performance.

How this skill works

The skill inspects common Convex query patterns and prescribes concrete handlers, validators, and calling conventions. It explains when to use ctx.db.query, how to attach indexes with withIndex, how to call queries from other functions via ctx.runQuery, and how to design paginated and full text search queries. It also highlights runtime limits and patterns to avoid slow operations.

When to use it

• When defining new Convex query functions to fetch structured data
• When implementing pagination for large result sets
• When creating or using indexes for efficient lookups
• When adding full text search or text filtering to queries
• When calling queries from mutations, actions, or other queries
• When optimizing query performance and ordering

Best practices

• Always include argument validators for every query function to enforce inputs
• Avoid client-side filtering; use withIndex and indexed conditions instead of filter
• Use .order('asc'|'desc') and .take(n) or .collect() to bound result size
• Implement pagination using pagination options (numItems and cursor) and return continueCursor/isDone
• Use ctx.runQuery to invoke queries from mutations or actions and annotate return types in the same file when needed
• Prefer .unique() for queries expected to return a single document and explicit null returns when appropriate

Example use cases

• Fetch latest messages for a channel using a by_channel index and .order('desc').take(20)
• Implement cursor-based pagination for feeds using paginationOpts and continueCursor
• Create custom compound indexes for multi-field lookups and use withIndex to query them
• Build a full text search index for message content and expose a search query that returns ranked results
• Call query functions from a mutation using ctx.runQuery to reuse read logic and keep mutations thin