Custom QuerySets in ORMBridge

What They Are

Pre-defined, reusable queries that encapsulate filtering logic, ordering, and access control.

Important: Custom querysets only modify what objects are returned, not how they're serialized. They must return a standard queryset of the model type.

Implementation

Custom querysets only change which objects are returned (filtering, ordering, etc.). They cannot:

• Add extra fields not in the model
• Change serialization behavior
• Transform the data structure
• Return anything other than a regular queryset

Server Side

from ormbridge.core.interfaces import AbstractCustomQueryset
from myapp.models import Product
from django.db.models import QuerySet

class ActiveProductsQuerySet(AbstractCustomQueryset):
    def get_queryset(self) -> QuerySet[Product]:
        # Must return a queryset of the model type, not modified data
        return Product.objects.filter(
            is_active=True,
            stock__gt=0
        ).order_by('-created_at')

# Register it
from ormbridge.adaptors.django.config import registry
registry.register_custom_queryset('active_products', ActiveProductsQuerySet)

Client Side

// Use the customQueryset method to access the predefined query
const products = await Product.objects.customQueryset('active_products').all();

// You can chain additional filters
const electronics = await Product.objects
  .customQueryset('active_products')
  .filter({ category: 'electronics' });

User-Scoped Queries

class UserOrdersQuerySet(AbstractCustomQueryset):
    def get_queryset(self, request=None):
        if not request or not request.user.is_authenticated:
            return Order.objects.none()
            
        if not request.user.is_staff:
            return Order.objects.filter(user=request.user)
            
        return Order.objects.all()

When to Use Custom QuerySets vs. Custom Filters

Custom QuerySets are better for:

• Complex queries that are used frequently
• Queries that need server-side context or optimization
• Consistent application of business rules
• Queries that combine multiple conditions

Custom Filters are better for:

• Ad-hoc filtering based on user input
• Simple, one-off query conditions
• Client-side composition of different filters
• Situations where query conditions vary widely