The @pxt.query Decorator: Building Reusable Database Queries for AI Agents and RAG Systems

The Query Repetition Problem in AI Applications#

Building AI agents and RAG systems means writing the same queries repeatedly: retrieving conversation history, finding relevant documents, fetching user context. Each time you need this logic, you copy-paste query code, creating duplication, inconsistency, and maintenance nightmares.

What if you could define these queries once and reuse them throughout your application? What if they could be as clean and composable as functions, while still benefiting from database optimization?

This is exactly what Pixeltable's @pxt.query decorator enables: reusable, parameterized database queries that work seamlessly with multimodal AI workflows.

Understanding @pxt.query: Queries as Functions#

The @pxt.query decorator transforms a Python function into a reusable query component. Instead of writing raw SQL or complex DataFrame operations, you define queries using Pixeltable's familiar table API:

The decorated function runs once, when it is decorated, with placeholders for its parameters. Parameters can appear in query expressions, but not in Python logic such as an if statement, and the function returns the query rather than calling .collect(). You then call it inside a select() or a computed column, where it runs once per row with that row's values.

AI Agent Memory: The Killer Use Case#

The most powerful application of @pxt.query is building stateful AI agents with persistent memory:

Pattern 1: Conversation History Retrieval#

Pattern 2: Semantic Memory Retrieval#

Build agents that retrieve relevant past experiences using embedding-based search:

RAG System Patterns: Optimized Context Retrieval#

Pattern 3: Hybrid Retrieval (Semantic + Metadata)#

Build sophisticated RAG systems that combine semantic search with metadata filtering:

Pattern 4: Multi-Source Knowledge Retrieval#

Query across multiple data sources for comprehensive multimodal RAG:

Performance Optimization with Query Patterns#

Pattern 5: Stored Results for Expensive Queries#

Call an expensive query from a computed column, and its result is stored with each row, so reading it later does not run the query again. Pixeltable does not cache query results: each new row runs the query, even for a user it has seen before.

Pattern 6: Context From Several Tables#

Pull context from several related tables into one row, with one query per table:

Advanced RAG Context Patterns#

Pattern 7: Time-Aware Context Retrieval#

Build RAG systems that consider temporal relevance:

Pattern 8: Multi-Hop Retrieval for Complex Questions#

Build queries that retrieve context in multiple steps:

Real-World Applications#

Customer Support: Contextual Ticket Routing#

@pxt.query vs. Manual Queries#

Aspect	Manual Queries	@pxt.query Decorator
Reusability	Copy-paste code everywhere	Define once, use everywhere
Maintenance	Update in multiple places	Single source of truth
Composability	Difficult to combine queries	Easily compose query functions
Testing	Test each instance separately	Test query function once
Computed Columns	Can't use in computed columns	Direct integration with declarative workflows

Best Practices for Query Patterns#

Design Principles#

• Single Responsibility: Each query should do one thing well
• Parameterization: Make queries flexible with sensible defaults
• Documentation: Write clear docstrings explaining query purpose
• Error Handling: Return empty results rather than raising errors
• Performance Awareness: Include limit parameters to prevent unbounded queries

Testing Query Functions#

Integration with AI Workflows#

Pattern 9: Query Functions as Agent Tools#

Convert query functions into agent tools for intelligent database access:

Conclusion: Query Patterns for Production AI#

The @pxt.query decorator transforms how you build AI applications by making database queries reusable, composable, and declarative. Instead of scattering query logic throughout your codebase, you define clear, tested query functions that integrate seamlessly with Pixeltable's declarative infrastructure.

This pattern is particularly powerful for:

• AI Agent Memory: Reusable context retrieval across conversations
• RAG Systems: Sophisticated hybrid retrieval with consistent logic
• Multi-Table Analytics: Lookups and aggregations across tables as simple functions
• Agent Tools: Database queries that AI agents can call intelligently

By treating queries as first-class components in your AI architecture, you build more maintainable, testable, and performant applications. Combined with custom aggregations (UDAs) and Python UDFs, you have complete control over your AI data workflows.

Master Reusable Query Patterns#

• @pxt.query SDK Reference: Official documentation
• Database to AI Tool Guide: Convert queries to agent tools
• AI Agent Architecture: Build agents with memory
• Production RAG Systems: Advanced retrieval patterns
• Your First Pixeltable Project: Get started with basics
• Pixeltable on GitHub: Examples and source code
• Join our Discord: Share your query patterns

Stop copying query code. Build reusable query patterns that scale with your AI applications. 🔍