Bài 9.1: Filtering, Searching & Pagination - Phần 1 - Basic Filtering

**Series Navigation:** - **Bài 9.1 (bài này): Basic Filtering** 👈 - [Bài 9.2: Advanced Filtering](/django-advance/filtering-searching-pagination-phan-2) - [Bài 9.3: Searching & Ordering](/django-advance/filtering-searching-pagination-phan-3) - [Bài 9.4: Pagination](/django-advance/filtering-searching-pagination-phan-4)

Mục Tiêu Bài 9.1

Sau khi hoàn thành Bài 9.1 này, bạn sẽ:

✅ Understand filtering in REST APIs
✅ Use DjangoFilterBackend
✅ Install and configure django-filter
✅ Create basic FilterSets
✅ Use field lookups
✅ Implement custom filter methods
✅ Handle filtering best practices

Why Filtering?

Problem Without Filtering

# Bad: Return all articlesGET /api/articles/# Returns 10,000 articles! # Client must filter locallyarticles = response.datapublished = [a for a in articles if a['status'] == 'published']

Issues:

❌ Transfers unnecessary data
❌ Slow response time
❌ Wastes bandwidth
❌ Client-side filtering inefficient

Solution: Server-Side Filtering

# Good: Filter on serverGET /api/articles/?status=published# Returns only published articles GET /api/articles/?status=published&author=5# Returns published articles by author #5

Benefits:

✅ Transfers only needed data
✅ Fast response (database filtering)
✅ Saves bandwidth
✅ Efficient queries

Basic Query Parameter Filtering

Manual Implementation

# views.pyfrom rest_framework import viewsetsfrom myapp.models import Articlefrom myapp.serializers import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer        def get_queryset(self):        """        Filter by query parameters        GET /api/articles/?status=published        GET /api/articles/?author=5        GET /api/articles/?status=published&author=5        """        queryset = super().get_queryset()                # Get query parameters        status = self.request.query_params.get('status')        author = self.request.query_params.get('author')                # Apply filters        if status:            queryset = queryset.filter(status=status)                if author:            queryset = queryset.filter(author_id=author)                return queryset

Usage:

# Filter by statuscurl "http://localhost:8000/api/articles/?status=published" # Filter by authorcurl "http://localhost:8000/api/articles/?author=5" # Multiple filterscurl "http://localhost:8000/api/articles/?status=published&author=5"

Problems with manual approach:

🔴 Repetitive code
🔴 No validation
🔴 Limited lookup types
🔴 Hard to maintain

DjangoFilterBackend

Installation

pip install django-filter

Configuration

# settings.pyINSTALLED_APPS = [    # ...    'django_filters',] REST_FRAMEWORK = {    'DEFAULT_FILTER_BACKENDS': [        'django_filters.rest_framework.DjangoFilterBackend',    ],}

Basic Usage

# views.pyfrom rest_framework import viewsetsfrom django_filters.rest_framework import DjangoFilterBackend class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend]    filterset_fields = ['status', 'author', 'category']        # Now supports:    # GET /api/articles/?status=published    # GET /api/articles/?author=5    # GET /api/articles/?category=tech    # GET /api/articles/?status=published&author=5

That's it! 3 lines enable filtering on multiple fields.

Per-View Configuration

# Configure per view (overrides global settings)class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend]  # Only for this view    filterset_fields = ['status', 'author']

FilterSet Basics

What is a FilterSet?

FilterSet = Defines which fields can be filtered and how.

Simple FilterSet

# filters.pyfrom django_filters import rest_framework as filtersfrom myapp.models import Article class ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = ['status', 'author', 'category'] # views.pyclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend]    filterset_class = ArticleFilter  # Use custom FilterSet

Field Lookups

Exact match (default):

class ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = ['status']  # Exact match only # Usage: /api/articles/?status=published

Multiple lookup types:

class ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = {            'title': ['exact', 'icontains'],            'status': ['exact'],            'author': ['exact'],            'created_at': ['gte', 'lte', 'exact'],            'views': ['gte', 'lte'],        } # Usage:# /api/articles/?title__icontains=django# /api/articles/?created_at__gte=2024-01-01# /api/articles/?created_at__lte=2024-12-31# /api/articles/?views__gte=1000

Available lookups:

# Text fields'exact'         # Exact match'iexact'        # Case-insensitive exact'contains'      # Contains (case-sensitive)'icontains'     # Contains (case-insensitive)'startswith'    # Starts with'istartswith'   # Case-insensitive starts with'endswith'      # Ends with'iendswith'     # Case-insensitive ends with # Numeric/Date fields'exact'         # Exact match'gt'            # Greater than'gte'           # Greater than or equal'lt'            # Less than'lte'           # Less than or equal'range'         # Between two values # Boolean fields'exact'         # True/False # Foreign keys'exact'         # Exact ID'in'            # List of IDs'isnull'        # Is null/not null

# models.pyclass Author(models.Model):    name = models.CharField(max_length=100)    email = models.EmailField() class Category(models.Model):    name = models.CharField(max_length=50) class Article(models.Model):    title = models.CharField(max_length=200)    author = models.ForeignKey(Author, on_delete=models.CASCADE)    category = models.ForeignKey(Category, on_delete=models.CASCADE)    status = models.CharField(max_length=20) # filters.pyclass ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = {            'title': ['icontains'],            'status': ['exact'],            'author': ['exact'],            'author__name': ['icontains'],      # Filter by author name            'author__email': ['iexact'],        # Filter by author email            'category': ['exact'],            'category__name': ['icontains'],    # Filter by category name        } # Usage:# /api/articles/?author__name__icontains=john# /api/articles/?author__email__iexact=john@example.com# /api/articles/?category__name__icontains=tech

Custom Filter Fields

CharFilter

# filters.pyimport django_filters as filters class ArticleFilter(filters.FilterSet):    # Custom char filter    title = filters.CharFilter(        field_name='title',        lookup_expr='icontains',        label='Title contains'    )        class Meta:        model = Article        fields = [] # Usage: /api/articles/?title=django# Equivalent to: Article.objects.filter(title__icontains='django')

NumberFilter

class ArticleFilter(filters.FilterSet):    min_views = filters.NumberFilter(        field_name='views',        lookup_expr='gte',        label='Minimum views'    )        max_views = filters.NumberFilter(        field_name='views',        lookup_expr='lte',        label='Maximum views'    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?min_views=1000# /api/articles/?max_views=5000# /api/articles/?min_views=1000&max_views=5000

DateFilter

class ArticleFilter(filters.FilterSet):    created_after = filters.DateFilter(        field_name='created_at',        lookup_expr='gte',        label='Created after'    )        created_before = filters.DateFilter(        field_name='created_at',        lookup_expr='lte',        label='Created before'    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?created_after=2024-01-01# /api/articles/?created_before=2024-12-31

DateTimeFilter

class ArticleFilter(filters.FilterSet):    published_after = filters.DateTimeFilter(        field_name='published_at',        lookup_expr='gte'    )        published_before = filters.DateTimeFilter(        field_name='published_at',        lookup_expr='lte'    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?published_after=2024-01-01T00:00:00Z# /api/articles/?published_before=2024-12-31T23:59:59Z

BooleanFilter

class ArticleFilter(filters.FilterSet):    is_featured = filters.BooleanFilter(        field_name='is_featured'    )        is_published = filters.BooleanFilter(        field_name='published_at',        lookup_expr='isnull',        exclude=True  # Invert: True if NOT null    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?is_featured=true# /api/articles/?is_featured=false# /api/articles/?is_published=true

ChoiceFilter

class Article(models.Model):    STATUS_CHOICES = [        ('draft', 'Draft'),        ('review', 'Under Review'),        ('published', 'Published'),        ('archived', 'Archived'),    ]    status = models.CharField(max_length=20, choices=STATUS_CHOICES) class ArticleFilter(filters.FilterSet):    status = filters.ChoiceFilter(        choices=Article.STATUS_CHOICES    )        class Meta:        model = Article        fields = [] # Usage: /api/articles/?status=published

MultipleChoiceFilter

class ArticleFilter(filters.FilterSet):    status = filters.MultipleChoiceFilter(        choices=Article.STATUS_CHOICES    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?status=published# /api/articles/?status=published&status=review  # Multiple values

ModelChoiceFilter

class ArticleFilter(filters.FilterSet):    author = filters.ModelChoiceFilter(        queryset=Author.objects.all()    )        category = filters.ModelChoiceFilter(        queryset=Category.objects.all()    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?author=5# /api/articles/?category=3

ModelMultipleChoiceFilter

class Article(models.Model):    title = models.CharField(max_length=200)    tags = models.ManyToManyField('Tag') class ArticleFilter(filters.FilterSet):    tags = filters.ModelMultipleChoiceFilter(        queryset=Tag.objects.all()    )        class Meta:        model = Article        fields = [] # Usage:# /api/articles/?tags=1&tags=2&tags=3# Returns articles with ANY of these tags

Custom Filter Methods

Method Filter

class ArticleFilter(filters.FilterSet):    search = filters.CharFilter(method='filter_search')        def filter_search(self, queryset, name, value):        """        Custom filter method        Search in title or content        """        return queryset.filter(            Q(title__icontains=value) |             Q(content__icontains=value)        )        class Meta:        model = Article        fields = [] # Usage: /api/articles/?search=django# Searches in both title and content

Complex Custom Filter

class ArticleFilter(filters.FilterSet):    author_or_editor = filters.CharFilter(method='filter_author_or_editor')        def filter_author_or_editor(self, queryset, name, value):        """        Filter by author name or editor name        """        return queryset.filter(            Q(author__name__icontains=value) |            Q(editors__name__icontains=value)        ).distinct()        min_score = filters.NumberFilter(method='filter_min_score')        def filter_min_score(self, queryset, name, value):        """        Filter by calculated score        """        from django.db.models import F, ExpressionWrapper, FloatField                # Calculate score: views * 0.5 + likes * 2        queryset = queryset.annotate(            score=ExpressionWrapper(                F('views') * 0.5 + F('likes') * 2,                output_field=FloatField()            )        )                return queryset.filter(score__gte=value)        class Meta:        model = Article        fields = []

Date Range Filter

class ArticleFilter(filters.FilterSet):    date_range = filters.CharFilter(method='filter_date_range')        def filter_date_range(self, queryset, name, value):        """        Filter by date range        Usage: ?date_range=2024-01-01,2024-12-31        """        try:            start_date, end_date = value.split(',')            return queryset.filter(                created_at__gte=start_date,                created_at__lte=end_date            )        except ValueError:            return queryset        class Meta:        model = Article        fields = []

Filtering Best Practices

1. Limit Filterable Fields

# Bad: Allow filtering on all fieldsclass ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = '__all__'  # Dangerous! # Good: Explicitly define filterable fieldsclass ArticleFilter(filters.FilterSet):    class Meta:        model = Article        fields = ['status', 'author', 'category', 'created_at']

2. Use Appropriate Lookups

# Bad: Allow all lookups on sensitive fieldsclass UserFilter(filters.FilterSet):    class Meta:        model = User        fields = {            'email': ['exact', 'icontains', 'startswith'],  # Privacy issue!        } # Good: Restrict lookups appropriatelyclass UserFilter(filters.FilterSet):    class Meta:        model = User        fields = {            'email': ['exact'],  # Only exact match        }

3. Add Indexes

# models.pyclass Article(models.Model):    status = models.CharField(max_length=20, db_index=True)  # Indexed    author = models.ForeignKey(Author, on_delete=models.CASCADE)  # Auto-indexed    created_at = models.DateTimeField(db_index=True)  # Indexed        class Meta:        indexes = [            models.Index(fields=['status', 'created_at']),  # Composite index            models.Index(fields=['author', 'status']),        ]

4. Validate Filter Values

class ArticleFilter(filters.FilterSet):    views = filters.NumberFilter(method='filter_views')        def filter_views(self, queryset, name, value):        """Validate before filtering"""        if value < 0:            return queryset  # Invalid, return unfiltered                return queryset.filter(views__gte=value)        class Meta:        model = Article        fields = []

class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.select_related('author', 'category').all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend]    filterset_class = ArticleFilter        # Prevents N+1 queries when filtering by related fields

Complete Example

# models.pyfrom django.db import modelsfrom django.contrib.auth.models import User class Category(models.Model):    name = models.CharField(max_length=50, unique=True)        def __str__(self):        return self.name class Tag(models.Model):    name = models.CharField(max_length=50, unique=True)        def __str__(self):        return self.name class Article(models.Model):    STATUS_CHOICES = [        ('draft', 'Draft'),        ('published', 'Published'),        ('archived', 'Archived'),    ]        title = models.CharField(max_length=200, db_index=True)    content = models.TextField()    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='articles')    category = models.ForeignKey(Category, on_delete=models.CASCADE)    tags = models.ManyToManyField(Tag, blank=True)    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='draft', db_index=True)    views = models.IntegerField(default=0)    likes = models.IntegerField(default=0)    created_at = models.DateTimeField(auto_now_add=True, db_index=True)    updated_at = models.DateTimeField(auto_now=True)    published_at = models.DateTimeField(null=True, blank=True)        class Meta:        ordering = ['-created_at']        indexes = [            models.Index(fields=['status', 'created_at']),            models.Index(fields=['author', 'status']),        ] # filters.pyfrom django_filters import rest_framework as filtersfrom django.db.models import Qfrom myapp.models import Article, Category, Tag class ArticleFilter(filters.FilterSet):    # Basic filters    title = filters.CharFilter(lookup_expr='icontains')    status = filters.ChoiceFilter(choices=Article.STATUS_CHOICES)        # Related filters    author = filters.NumberFilter(field_name='author__id')    author_name = filters.CharFilter(field_name='author__username', lookup_expr='icontains')    category = filters.ModelChoiceFilter(queryset=Category.objects.all())    tags = filters.ModelMultipleChoiceFilter(queryset=Tag.objects.all())        # Date filters    created_after = filters.DateFilter(field_name='created_at', lookup_expr='gte')    created_before = filters.DateFilter(field_name='created_at', lookup_expr='lte')    published_after = filters.DateTimeFilter(field_name='published_at', lookup_expr='gte')    published_before = filters.DateTimeFilter(field_name='published_at', lookup_expr='lte')        # Number filters    min_views = filters.NumberFilter(field_name='views', lookup_expr='gte')    max_views = filters.NumberFilter(field_name='views', lookup_expr='lte')    min_likes = filters.NumberFilter(field_name='likes', lookup_expr='gte')        # Custom filters    search = filters.CharFilter(method='filter_search')    popular = filters.BooleanFilter(method='filter_popular')        def filter_search(self, queryset, name, value):        """Search in title, content, or author name"""        return queryset.filter(            Q(title__icontains=value) |            Q(content__icontains=value) |            Q(author__username__icontains=value)        ).distinct()        def filter_popular(self, queryset, name, value):        """Filter popular articles (views >= 1000 or likes >= 100)"""        if value:            return queryset.filter(                Q(views__gte=1000) | Q(likes__gte=100)            )        return queryset        class Meta:        model = Article        fields = [] # serializers.pyfrom rest_framework import serializers class ArticleSerializer(serializers.ModelSerializer):    author_name = serializers.CharField(source='author.username', read_only=True)    category_name = serializers.CharField(source='category.name', read_only=True)    tag_names = serializers.StringRelatedField(source='tags', many=True, read_only=True)        class Meta:        model = Article        fields = [            'id', 'title', 'content', 'author', 'author_name',            'category', 'category_name', 'tag_names', 'status',            'views', 'likes', 'created_at', 'updated_at', 'published_at'        ] # views.pyfrom rest_framework import viewsetsfrom django_filters.rest_framework import DjangoFilterBackendfrom myapp.models import Articlefrom myapp.serializers import ArticleSerializerfrom myapp.filters import ArticleFilter class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.select_related('author', 'category').prefetch_related('tags').all()    serializer_class = ArticleSerializer    filter_backends = [DjangoFilterBackend]    filterset_class = ArticleFilter # urls.pyfrom rest_framework.routers import DefaultRouterfrom myapp.views import ArticleViewSet router = DefaultRouter()router.register('articles', ArticleViewSet, basename='article') urlpatterns = router.urls

API Usage Examples:

# Basic filtersGET /api/articles/?status=publishedGET /api/articles/?title__icontains=djangoGET /api/articles/?author=5 # Related filtersGET /api/articles/?author_name__icontains=johnGET /api/articles/?category=3GET /api/articles/?tags=1&tags=2 # Date filtersGET /api/articles/?created_after=2024-01-01GET /api/articles/?created_before=2024-12-31GET /api/articles/?published_after=2024-01-01T00:00:00Z # Number filtersGET /api/articles/?min_views=1000GET /api/articles/?max_views=5000GET /api/articles/?min_likes=100 # Custom filtersGET /api/articles/?search=djangoGET /api/articles/?popular=true # Combined filtersGET /api/articles/?status=published&min_views=1000&created_after=2024-01-01

Tóm Tắt Bài 9.1

Trong Bài 9.1 này, bạn đã học:

✅ Why Filtering:

Server-side vs client-side
Benefits of API filtering
Query parameter basics

✅ DjangoFilterBackend:

Installation & configuration
Basic usage with filterset_fields
Per-view configuration

✅ FilterSet Basics:

What is a FilterSet
Simple FilterSet
Field lookups (exact, icontains, gte, lte, etc.)
Related field filtering

✅ Custom Filter Fields:

CharFilter, NumberFilter, DateFilter
BooleanFilter, ChoiceFilter
ModelChoiceFilter, ModelMultipleChoiceFilter

✅ Custom Filter Methods:

Method filters
Complex filtering logic
Date range filters

✅ Best Practices:

Limit filterable fields
Appropriate lookups
Add database indexes
Validate filter values
Use select_related

Next Steps

Trong Bài 9.2, bạn sẽ học:

Advanced filtering techniques
Range filters
OrderingFilter
Custom filter backends
Filtering optimization

Navigation:

Bài 8.4: Advanced Authorization Patterns
Bài 9.1: Basic Filtering (current)
Bài 9.2: Advanced Filtering →

#query-parameters

Filtering, Searching & Pagination - Phần 1 - Basic Filtering