Search & Query Parameters0%
Pagination Techniques

Search & Query Parameters

Beginner12 min read•Updated: Jul 11, 2026
Study MaterialsCheatsheet

DRF SearchFilter and OrderingFilter

While DjangoFilterBackend performs exact and structured field matches, users frequently need a single search input to query multiple text fields simultaneously (e.g. searching across customer name, order ID, and notes), as well as interactive column sorting. DRF includes SearchFilter and OrderingFilter out of the box.

1. Enabling SearchFilter and OrderingFilter

Configure backends on your ViewSet:

Python
# api/views.py
from rest_framework.viewsets import ModelViewSet
from rest_framework.filters import SearchFilter, OrderingFilter
from django_filters.rest_framework import DjangoFilterBackend
from .models import Article
from .serializers import ArticleSerializer
 
class ArticleViewSet(ModelViewSet):
queryset = Article.objects.select_related("author").all()
serializer_class = ArticleSerializer
# Enable all three complementary backends
filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
# 1. Exact field filtering
filterset_fields = ["status", "category"]
# 2. Text search fields
search_fields = ["title", "content", "author__username", "=slug"]
# 3. Dynamic sorting fields
ordering_fields = ["created_at", "view_count", "title"]
ordering = ["-created_at"] # Default fallback ordering

2. Advanced Search Prefixes

DRF's SearchFilter supports regex and lookup prefixes in search_fields:

PrefixLookup SyntaxMeaningExample
(None)icontainsCase-insensitive partial match"title" matches "django" anywhere in title
^istartswithCase-insensitive prefix match"^title" matches words starting with term
=iexactCase-insensitive exact match"=slug" matches exact slug string only
@Full-textPostgreSQL full-text search index"@content" (PostgreSQL only)
$RegexCase-insensitive regular expression"$title" matches regex pattern
Python
search_fields = ["^title", "=slug", "author__email"]

3. Client URL Usage

Clients use the ?search= and ?ordering= query parameters:

Multi-column Text Search:

HTTP
# Searches for 'microservice' in title, content, or author username
GET /api/v1/articles/?search=microservice

Dynamic Column Sorting:

HTTP
# Sort ascending by view_count:
GET /api/v1/articles/?ordering=view_count
 
# Sort descending by view_count (using minus sign '-'):
GET /api/v1/articles/?ordering=-view_count
 
# Multi-column sorting (views descending, then title ascending):
GET /api/v1/articles/?ordering=-view_count,title

4. Customizing Query Parameter Names

If your API convention requires ?q= instead of ?search= or ?sort= instead of ?ordering=:

Python
# config/settings.py
REST_FRAMEWORK = {
"SEARCH_PARAM": "q",
"ORDERING_PARAM": "sort",
}

Now requests can use /api/v1/articles/?q=docker&sort=-created_at.

Interactive Quiz

Practice Quiz

Question 1
What query parameter does DRF's SearchFilter inspect by default?
Question 2
What search prefix enforces an exact case-insensitive match (=slug) in search_fields?
Question 3
How does a client specify descending sort order using DRF's OrderingFilter?
Question 4
Why is it critical to explicitly define ordering_fields on your ViewSet?
Question 5
How do you sort by multiple columns simultaneously with OrderingFilter?
Next Lesson

Pagination Techniques

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous LessonNext Lesson
Filtering API resultsPagination Techniques

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

PreviousNext
PrevNext