django-virtual-models

Django Virtual Models introduces a "prefetching layer" to help manage complex read logic in Django and Django REST Framework (DRF) projects.

Instead of manually managing complex chains of select_related, prefetch_related, and annotate calls in your view querysets—which is error-prone and often leads to N+1 query problems—you can declare all nesting, annotations, and joins in a single, reusable, and declarative VirtualModel class.

Key benefits include:

• Performance: Prevents N+1 select problems by ensuring all necessary prefetches are included.
• Maintainability: Keeps complex query logic bundled with the data structure it represents.
• Safety: When used with DRF, the library validates that your VirtualModel covers all fields required by your VirtualModelSerializer. If a field is missing, it raises a MissingVirtualModelFieldException to guide you toward the correct implementation.

Virtual Models can access dynamic data passed through the request or serializer context. This allows for user-specific annotations or filtered prefetches.

Accessing the Current User

In v.Annotation, the user argument is automatically injected from self.context["request"].user. In get_prefetch_queryset, the user argument is also available.

class VirtualMovie(v.VirtualModel):
    user_rating = v.Annotation(
        lambda qs, user, **kwargs: qs.annotate(
            Subquery(
                UserMovieRating.objects.filter(
                    movie=OuterRef("pk"),
                    user=user
                ).values("rating")[:1]
            )
        )
    )

    class Meta:
        model = Movie

Accessing Serializer Context

You can pass custom data from a view to the serializer via get_serializer_context, and then access it in a v.Annotation using the serializer_context argument.

# In the View
def get_serializer_context(self):
    context = super().get_serializer_context()
    return {**context, 'vote_value': 5}

# In the Virtual Model
class VirtualMovie(v.VirtualModel):
    voting_count = v.Annotation(
        lambda qs, user, serializer_context, **kwargs: qs.annotate(
            voting_count=Count("ratings", filter=Q(ratings__rating=serializer_context['vote_value']))
        )
    )

    class Meta:
        model = Movie

To define a Virtual Model, inherit from django_virtual_models.VirtualModel. You can declare nested Virtual Models using the same syntax as DRF serializers and define annotations using v.Annotation.

• Use class Meta: model = YourModel to specify the base model.
• Use v.Annotation to define queryset-level computations.
• Nest other Virtual Models to represent relationships, using the lookup argument to specify the related name/field.

import django_virtual_models as v

class VirtualAward(v.VirtualModel):
    class Meta:
        model = Nomination

    def get_prefetch_queryset(self, **kwargs):
        return Nomination.objects.filter(is_winner=True)


class VirtualPerson(v.VirtualModel):
    # Nesting a Virtual Model with a lookup
    awards = VirtualAward(lookup="nominations")
    
    # Defining an annotation
    nomination_count = v.Annotation(
        lambda qs, **kwargs: qs.annotate(
            nomination_count=Count("nominations")
        ).distinct()
    )

    class Meta:
        model = Person


class VirtualMovie(v.VirtualModel):
    # Nesting another Virtual Model
    directors = VirtualPerson()

    class Meta:
        model = Movie

To prevent N+1 queries and manage complex querysets, use VirtualModel and VirtualModelSerializer to create a layer that defines exactly which fields (annotations, prefetches, etc.) a serializer requires.

1. Define a VirtualModel: Create a class inheriting from v.VirtualModel and specify the target model in class Meta.
2. Define a VirtualModelSerializer: Use v.VirtualModelSerializer and link it to your virtual model using the virtual_model attribute in class Meta.
3. Use Virtual View Classes: Use v.VirtualModelListAPIView or v.VirtualModelRetrieveAPIView instead of standard DRF views to ensure the optimized queryset is automatically applied.

Note: If you override get_queryset in your view, you must call super().get_queryset() to maintain integration. If using custom base views, use GenericVirtualModelViewMixin.

import django_virtual_models as v

class VirtualMovie(v.VirtualModel):
    class Meta:
        model = Movie

class MovieSerializer(v.VirtualModelSerializer):
    directors = PersonSerializer(many=True)

    class Meta:
        model = Movie
        virtual_model = VirtualMovie
        fields = ["name", "directors"]

class MovieListView(v.VirtualModelListAPIView):
    serializer_class = MovieSerializer
    queryset = Movie.objects.all()