Convex Queries

Convex Queries Skill

This skill provides specialized guidance for implementing Convex query functions, including best practices for function definition, registration, calling patterns, pagination, indexing, and full text search.

When to Use This Skill

Use this skill when:

• Defining new query functions to fetch data from the Convex database
• Implementing pagination for large result sets
• Setting up indexes for efficient querying
• Using full text search functionality
• Calling queries from other Convex functions
• Optimizing query performance

Skill Resources

This skill includes comprehensive reference documentation in references/query-guidelines.md that covers:

Core Query Development

• Function definition syntax using the new function syntax
• Query registration (query and internalQuery)
• Argument validators and their usage
• Function calling patterns (ctx.runQuery)
• Function references (api and internal objects)
• File-based routing for query paths

Query Optimization

• Query guidelines (avoiding filter, using indexes with withIndex)
• Ordering results with .order('asc') and .order('desc')
• Using .unique() for single document retrieval
• Async iteration with for await syntax
• Query limits and performance considerations

Advanced Query Features

• Pagination: Implementing paginated queries with paginationOptsValidator
  • Understanding paginationOpts (numItems and cursor)
  • Reading paginated results (page, isDone, continueCursor)
• Full Text Search: Setting up and querying search indexes
• Indexing: Creating and using indexes for efficient lookups
  • Built-in indexes (by_id, by_creation_time)
  • Custom index naming and field ordering
  • Nested queries with multiple indexes

Database Queries

• Reading from the Convex database with ctx.db.query()
• Index usage with .withIndex()
• Result collection with .collect() and .take(n)

How to Use This Skill

1. Read the reference documentation at references/query-guidelines.md to understand the complete query patterns
2. Follow the syntax examples for defining query functions with proper validators
3. Use indexes for efficient filtering instead of the filter method
4. Implement pagination when dealing with large datasets
5. Leverage full text search for text-based filtering needs
6. Optimize ordering by understanding how Convex orders results

Key Query Guidelines

• ALWAYS include argument validators for all query functions
• Do NOT use filter in queries; use withIndex instead
• Use ctx.runQuery to call queries from mutations or actions
• Specify return type annotations when calling queries in the same file (TypeScript circularity workaround)
• Queries execute for at most 1 second and can read up to 16384 documents
• Return null implicitly if your query doesn't have an explicit return value

Example: Basic Query with Index

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);
  },
});

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