Skip to content

Django Selectors — the data reading layer

selectors.py is a separate file in every Django app where all ORM queries for READING data live. A selector is a named, reusable query.


The problem without Selectors

In any Django project, code like this appears very quickly:

# views.py
Post.objects.filter(is_active=True, published_at__lte=timezone.now())

# tasks.py
Post.objects.filter(is_active=True, published_at__lte=timezone.now())

# admin.py
Post.objects.filter(is_active=True, published_at__lte=timezone.now())

# services.py
Post.objects.filter(is_active=True, published_at__lte=timezone.now())

The same query is copied into 20 places.

What happens next: - The business logic changes (a new is_deleted field is added) — 20 places need updating - Each developer writes the query slightly differently — inconsistencies in behavior - It is unclear where to optimize select_related centrally - The code reads like SQL, not like the business domain


The solution: a Selector

# apps/blog/selectors.py

from django.utils import timezone
from apps.blog.models import Post


def get_published_posts():
    return Post.objects.filter(
        is_active=True,
        published_at__lte=timezone.now()
    )

Now everywhere:

# views.py
from apps.blog.selectors import get_published_posts

posts = get_published_posts()

# tasks.py
posts = get_published_posts()

# services.py
posts = get_published_posts()

The logic is in one place. A change is made in one place.


What a Selector is architecturally

A selector is an abstraction over the intent of a query.

Level Responsible for Example
PostgreSQL Stores data SELECT ... WHERE ...
ORM How to get the data Post.objects.filter(...)
Selector WHAT we want (business language) get_published_posts()
View / Service Orchestration posts = get_published_posts()

A selector hides the ORM and returns a domain name:

# ORM — technical language
Post.objects.filter(Q(author=user) | Q(is_public=True)).select_related('author')

# Selector — domain language
get_visible_posts_for_user(user=user)

CQRS-light: Reads vs Writes

In a Django architecture, the business layer is split into two clear roles:

services.py   →   WRITE / State change
selectors.py  →   READ  / State reading

This is a simplified version of the CQRS (Command Query Responsibility Segregation) pattern:

Services Selectors
Role Command — changes state Query — reads state
Operations CREATE, UPDATE, DELETE SELECT
Transactions @transaction.atomic No
Side effects Yes (email, Celery) Never
Returns The domain object after changes A QuerySet or data

The main rule: A selector never changes data.

# BAD — a selector that mutates data
def get_or_create_user(email):
    user, _ = User.objects.get_or_create(email=email)  # CREATE — this is not a selector
    return user

# GOOD — split it
# selectors.py
def get_user_by_email(*, email: str):
    return User.objects.filter(email=email).first()

# services.py
def user_create(*, email: str, name: str) -> User:
    user = User(email=email, name=name)
    user.full_clean()
    user.save()
    return user

Anatomy of a Selector

Basic rules (the same as for Services)

  • Lives in <app_name>/selectors.py
  • A stateless Python function (not a class)
  • Keyword-only arguments (*) — protection against argument-order mistakes
  • Strict type annotations
  • Knows nothing about HTTP, does not import DRF
# apps/flood/selectors.py

from django.db.models import QuerySet, Count
from apps.flood.models import FloodEvent, Region


def flood_event_get_by_id(*, event_id: int) -> FloodEvent:
    """Returns one object or raises DoesNotExist."""
    return FloodEvent.objects.get(id=event_id)


def flood_events_get_for_region(*, region_id: int) -> QuerySet:
    """All events for a region with optimized JOINs."""
    return (
        FloodEvent.objects
        .filter(region_id=region_id)
        .select_related('region', 'created_by')
        .prefetch_related('satellite_images')
        .order_by('-detected_at')
    )


def flood_events_get_visible_for(*, user) -> QuerySet:
    """
    Hides complex Q logic behind a domain name.
    The caller does not know the filtering details.
    """
    from django.db.models import Q
    return (
        FloodEvent.objects
        .filter(Q(created_by=user) | Q(is_public=True))
        .select_related('region')
        .annotate(image_count=Count('satellite_images'))
        .order_by('-detected_at')
    )

Centralizing ORM optimizations

The main technical advantage of Selectors is that N+1 is solved in one place.

The problem: a query in a model property

# BAD — a hidden query on every access
class FloodEvent(models.Model):

    @property
    def region_name(self):
        return self.region.display_name   # SELECT every time

# In a template or serializer:
for event in events:           # 1 query
    print(event.region_name)   # + N queries → N+1 disaster
# GOOD — one JOIN at the SQL level
def flood_events_get_list() -> QuerySet:
    return (
        FloodEvent.objects
        .all()
        .select_related('region')          # JOIN for ForeignKey
        .prefetch_related('tags')          # batched SELECT for M2M
        .annotate(
            comment_count=Count('comments')  # computed in SQL, not Python
        )
    )

# Now in the loop — ZERO additional queries
for event in flood_events_get_list():
    print(event.region.display_name)   # already in memory
    print(event.comment_count)         # already there from annotate

When to use what

ORM method When Relationship type
select_related() ForeignKey, OneToOne JOIN at the SQL level
prefetch_related() ManyToMany, reverse FK Separate SELECT + Python join
annotate() Aggregates, computations SQL GROUP BY / subquery
only(*fields) Huge models, 2-3 fields needed Partial SELECT
defer(*fields) Exclude heavy fields (e.g. TextField) Partial SELECT

QuerySet vs evaluated result

A selector can return two kinds of things:

QuerySet (a query not yet executed)

def flood_events_get_list() -> QuerySet:
    return FloodEvent.objects.filter(is_active=True).select_related('region')

When: The view can safely add pagination, django_filters, .count().

# View
queryset = flood_events_get_list()

# DRF pagination — safe, the QuerySet has not been executed yet
page = self.paginate_queryset(queryset)

Evaluated list / dict

def flood_events_get_summary(*, user) -> list[dict]:
    """A complex structure — built in Python after a single SQL query."""
    events = (
        FloodEvent.objects
        .filter(created_by=user)
        .select_related('region')
        .values('id', 'region__display_name', 'severity_level', 'detected_at')
    )

    return [
        {
            'id': e['id'],
            'region': e['region__display_name'],
            'severity': e['severity_level'],
            'detected_at': e['detected_at'].isoformat(),
        }
        for e in events
    ]

When: Complex data transformation, an in-memory cache, working around the limitations of nested serializers.


Selector + django-filter (no ORM leaking into the View)

# apps/flood/filters.py
import django_filters
from apps.flood.models import FloodEvent

class FloodEventFilter(django_filters.FilterSet):
    severity  = django_filters.ChoiceFilter(choices=FloodEvent.SEVERITY_CHOICES)
    after     = django_filters.DateTimeFilter(field_name='detected_at', lookup_expr='gte')

    class Meta:
        model  = FloodEvent
        fields = ['severity', 'after']
# apps/flood/views.py
class FloodEventListAPIView(ListAPIView):

    def get_queryset(self):
        qs = flood_events_get_visible_for(user=self.request.user)  # selector
        return FloodEventFilter(self.request.GET, queryset=qs).qs  # filter

The view does not know SQL. The selector does not know about query params. The filter does not know the business rules.


The full workflow

HTTP GET /api/flood/events/?severity=high
        │
        ▼
┌──────────────────────────────────────┐
│  View                                │
│  Calls the selector                  │
│  Passes the QuerySet to the filter   │
│  Paginates the result                │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  Selector                            │
│  flood_events_get_visible_for(user)  │
│  select_related('region')            │
│  annotate(image_count=Count(...))    │
│  Returns a QuerySet                  │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  ORM                                 │
│  Compiles into optimal SQL           │
│  SELECT flood_event.*, region.*,     │
│         COUNT(images.id)             │
│  FROM flood_event                    │
│  JOIN region ON ...                  │
│  WHERE (created_by=$1 OR is_public)  │
│  AND severity='high'                 │
└──────────────┬───────────────────────┘
               │
               ▼
         PostgreSQL
               │
               ▼
    One optimized query

Naming Convention

Selectors should be named so that they read like business phrases:

# Get one object
user_get_by_id(*, user_id: int) -> User
flood_event_get_by_id(*, event_id: int) -> FloodEvent

# Get a list
flood_events_get_list() -> QuerySet
flood_events_get_visible_for(*, user) -> QuerySet
users_get_active() -> QuerySet

# Get with a filter
papers_get_unvalidated() -> QuerySet
jobs_get_failed_since(*, since: datetime) -> QuerySet
dem_candidates_get_best_for_region(*, region_id: int) -> QuerySet

The name says WHAT is needed. The ORM inside says HOW to get it.


What a Selector must NOT do

Action Why not
obj.save() This is a mutation — the Service's job
obj.delete() This is a mutation — the Service's job
get_or_create() Mutates data — this is a Service
Open @transaction.atomic Only the Service is responsible for transactions
Send email or start Celery Side effects — Service only
Know about request or Response A selector does not know HTTP

Quick cheat sheet

# selectors.py — template

from apps.<app>.models import <Model>


def <model>_get_by_id(*, <model>_id: int) -> <Model>:
    return <Model>.objects.get(id=<model>_id)


def <model>s_get_list() -> QuerySet:
    return (
        <Model>.objects
        .all()
        .select_related('<fk_field>')
        .prefetch_related('<m2m_field>')
        .order_by('-created_at')
    )


def <model>s_get_for_<condition>(*, <param>) -> QuerySet:
    return (
        <Model>.objects
        .filter(<field>=<param>)
        .select_related('<fk_field>')
    )

Connection to the rest of the documentation

Topic File
Services (business logic, mutations, transactions) DJANGO_SERVICES.md
Services + Selectors + Serializers (the full picture) DJANGO_SERVICES_SELECTORS.md
ORM: QuerySet API, N+1, select_related DJANGO_ORM_DEEP.md
Views: how to call a Selector from a View notes_chat_app/README.md — Step 8