Bài 9.4: Filtering, Searching & Pagination - Phần 4 - Pagination

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

Mục Tiêu Bài 9.4

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

✅ Understand pagination importance
✅ Use PageNumberPagination
✅ Use LimitOffsetPagination
✅ Use CursorPagination
✅ Create custom pagination
✅ Handle pagination best practices

Why Pagination?

Problem Without Pagination

# Bad: Return all recordsGET /api/articles/# Returns 100,000 articles! Response:{    "count": 100000,    "results": [... 100000 articles ...]}

Issues:

❌ Huge response size
❌ Slow query execution
❌ High memory usage
❌ Poor user experience
❌ Server overload

Solution: Pagination

# Good: Return page by pageGET /api/articles/?page=1# Returns 20 articles Response:{    "count": 100000,    "next": "http://api.example.com/articles/?page=2",    "previous": null,    "results": [... 20 articles ...]}

Benefits:

✅ Small response size
✅ Fast queries
✅ Low memory usage
✅ Good UX
✅ Scalable

PageNumberPagination

Basic Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',    'PAGE_SIZE': 20}

Now all list endpoints are paginated:

GET /api/articles/# Returns page 1 with 20 items GET /api/articles/?page=2# Returns page 2 with 20 items

Response Format

{    "count": 100,    "next": "http://localhost:8000/api/articles/?page=3",    "previous": "http://localhost:8000/api/articles/?page=1",    "results": [        {            "id": 21,            "title": "Article 21",            "content": "..."        },        // ... 19 more articles    ]}

Custom PageNumberPagination

# pagination.pyfrom rest_framework.pagination import PageNumberPagination class StandardResultsSetPagination(PageNumberPagination):    page_size = 20    page_size_query_param = 'page_size'    max_page_size = 100 # views.pyclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    pagination_class = StandardResultsSetPagination # Usage:# /api/articles/                    # 20 items per page (default)# /api/articles/?page_size=50       # 50 items per page# /api/articles/?page_size=200      # 100 items (capped at max)

Configuration Options

class CustomPageNumberPagination(PageNumberPagination):    # Default page size    page_size = 10        # Query parameter name for page number    page_query_param = 'page'        # Allow client to set page size    page_size_query_param = 'page_size'        # Maximum page size (prevents abuse)    max_page_size = 100        # First/last page links    last_page_strings = ('last',) # Usage:# /api/articles/?page=1&page_size=50# /api/articles/?page=last

Custom Response Format

class CustomPageNumberPagination(PageNumberPagination):    page_size = 20        def get_paginated_response(self, data):        return Response({            'pagination': {                'count': self.page.paginator.count,                'page': self.page.number,                'pages': self.page.paginator.num_pages,                'page_size': self.page_size,                'next': self.get_next_link(),                'previous': self.get_previous_link(),            },            'results': data        }) # Response:{    "pagination": {        "count": 100,        "page": 2,        "pages": 5,        "page_size": 20,        "next": "http://...",        "previous": "http://..."    },    "results": [...]}

LimitOffsetPagination

Basic Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',    'PAGE_SIZE': 20}

Usage:

GET /api/articles/?limit=20&offset=0   # First 20 itemsGET /api/articles/?limit=20&offset=20  # Next 20 itemsGET /api/articles/?limit=20&offset=40  # Items 41-60

Response Format

{    "count": 100,    "next": "http://localhost:8000/api/articles/?limit=20&offset=40",    "previous": "http://localhost:8000/api/articles/?limit=20&offset=0",    "results": [...]}

Custom LimitOffsetPagination

# pagination.pyfrom rest_framework.pagination import LimitOffsetPagination class CustomLimitOffsetPagination(LimitOffsetPagination):    # Default limit    default_limit = 20        # Query parameter names    limit_query_param = 'limit'    offset_query_param = 'offset'        # Maximum limit    max_limit = 100 # views.pyclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    pagination_class = CustomLimitOffsetPagination # Usage:# /api/articles/?limit=50&offset=100

When to Use LimitOffsetPagination?

Use when:

✅ Need to jump to arbitrary offset
✅ Implementing infinite scroll
✅ Client controls exact range

Don't use when:

❌ Very large datasets (slow with high offsets)
❌ Frequently changing data

CursorPagination

Why CursorPagination?

Problem with PageNumberPagination:

Page 1: Items 1-20[New item added]Page 2: Items 22-41 (item 21 duplicated from page 1!)

CursorPagination:

Uses cursor (encoded position)
No duplicates/skips even if data changes
Fast for large datasets
Only forward/backward (no random access)

Basic Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',    'PAGE_SIZE': 20}

Custom CursorPagination

# pagination.pyfrom rest_framework.pagination import CursorPagination class ArticleCursorPagination(CursorPagination):    page_size = 20    page_size_query_param = 'page_size'    max_page_size = 100    ordering = '-created_at'  # Required!    cursor_query_param = 'cursor' # views.pyclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer    pagination_class = ArticleCursorPagination # Usage:# /api/articles/# /api/articles/?cursor=cD0yMDI0LTAxLTAx

Response Format

{    "next": "http://localhost:8000/api/articles/?cursor=cD0yMDI0LTAxLTAx",    "previous": null,    "results": [...]}

Note: No count field (would require expensive query)

Multiple Ordering Fields

class ArticleCursorPagination(CursorPagination):    page_size = 20    ordering = ['-created_at', 'id']  # Multiple fields for uniqueness # Ensures stable ordering even with duplicate created_at values

When to Use CursorPagination?

Use when:

✅ Large datasets
✅ Frequently changing data
✅ Real-time feeds
✅ Infinite scroll

Don't use when:

❌ Need total count
❌ Need random page access
❌ Need to show page numbers

Custom Pagination

Custom Pagination Class

# pagination.pyfrom rest_framework.pagination import BasePaginationfrom rest_framework.response import Response class CustomPagination(BasePagination):    """    Custom pagination implementation    """        def paginate_queryset(self, queryset, request, view=None):        """        Paginate the queryset        Returns None if pagination is disabled        """        # Get page size from query params or default        self.page_size = int(request.query_params.get('page_size', 20))        self.page_number = int(request.query_params.get('page', 1))                # Calculate offset        offset = (self.page_number - 1) * self.page_size                # Get total count        self.count = queryset.count()                # Get page items        self.results = list(queryset[offset:offset + self.page_size])                # Store request for later        self.request = request                return self.results        def get_paginated_response(self, data):        """        Return paginated response        """        return Response({            'meta': {                'total': self.count,                'page': self.page_number,                'page_size': self.page_size,                'total_pages': (self.count + self.page_size - 1) // self.page_size,            },            'data': data        })

Keyset Pagination

class KeysetPagination(BasePagination):    """    Keyset pagination (using ID-based cursor)    Fast and efficient for large datasets    """    page_size = 20        def paginate_queryset(self, queryset, request, view=None):        # Get last_id from query params        last_id = request.query_params.get('last_id')                if last_id:            queryset = queryset.filter(id__lt=last_id)                # Get page_size + 1 to check if there's next page        self.results = list(queryset[:self.page_size + 1])        self.has_next = len(self.results) > self.page_size                if self.has_next:            self.results = self.results[:-1]                self.request = request                return self.results        def get_paginated_response(self, data):        last_id = self.results[-1].id if self.results else None                next_url = None        if self.has_next and last_id:            next_url = self.request.build_absolute_uri()            next_url += f'{"&" if "?" in next_url else "?"}last_id={last_id}'                return Response({            'next': next_url,            'results': data        }) # Usage:# /api/articles/                   # First page# /api/articles/?last_id=100       # Next page after ID 100

Header-Based Pagination

class HeaderPagination(PageNumberPagination):    """    Pagination info in headers, not body    """        def get_paginated_response(self, data):        return Response(            data,            headers={                'X-Total-Count': self.page.paginator.count,                'X-Page': self.page.number,                'X-Page-Size': self.page_size,                'X-Total-Pages': self.page.paginator.num_pages,                'Link': self.get_link_header(),            }        )        def get_link_header(self):        """Generate Link header (RFC 5988)"""        links = []                if self.get_next_link():            links.append(f'<{self.get_next_link()}>; rel="next"')                if self.get_previous_link():            links.append(f'<{self.get_previous_link()}>; rel="prev"')                return ', '.join(links) # Response:# Headers:#   X-Total-Count: 100#   X-Page: 2#   X-Page-Size: 20#   X-Total-Pages: 5#   Link: <http://...?page=3>; rel="next", <http://...?page=1>; rel="prev"# Body:#   [... array of items ...]

Conditional Pagination

class ConditionalPagination(PageNumberPagination):    """    Disable pagination for certain conditions    """    page_size = 20        def paginate_queryset(self, queryset, request, view=None):        # Disable pagination if ?paginate=false        if request.query_params.get('paginate', 'true').lower() == 'false':            return None                # Disable for certain actions        if hasattr(view, 'action') and view.action == 'export':            return None                return super().paginate_queryset(queryset, request, view) # Usage:# /api/articles/                    # Paginated# /api/articles/?paginate=false     # Not paginated

Pagination Best Practices

1. Always Set max_page_size

# Bad: No limitclass BadPagination(PageNumberPagination):    page_size = 20    page_size_query_param = 'page_size'    # Client can request unlimited items! # Good: Set maximumclass GoodPagination(PageNumberPagination):    page_size = 20    page_size_query_param = 'page_size'    max_page_size = 100  # Limit to prevent abuse

2. Use Appropriate Pagination Style

# Small datasets, need total count, page numberspagination_class = PageNumberPagination # Need offset control, arbitrary positioningpagination_class = LimitOffsetPagination # Large datasets, real-time feeds, frequently changingpagination_class = CursorPagination

3. Optimize Count Queries

class OptimizedPageNumberPagination(PageNumberPagination):    """    Cache count for expensive queries    """    page_size = 20        def get_count(self, queryset):        """Cache count query"""        from django.core.cache import cache                # Create cache key        cache_key = f'pagination_count:{queryset.model.__name__}'                # Check cache        count = cache.get(cache_key)                if count is None:            count = super().get_count(queryset)            cache.set(cache_key, count, 300)  # Cache 5 minutes                return count

4. Add Indexes for Ordering

# models.pyclass Article(models.Model):    title = models.CharField(max_length=200)    created_at = models.DateTimeField(auto_now_add=True, db_index=True)    views = models.IntegerField(default=0, db_index=True)        class Meta:        indexes = [            models.Index(fields=['-created_at']),  # For pagination ordering            models.Index(fields=['-views']),        ]

5. Use select_related/prefetch_related

class ArticleViewSet(viewsets.ModelViewSet):    serializer_class = ArticleSerializer    pagination_class = StandardResultsSetPagination        def get_queryset(self):        return Article.objects.select_related(            'author', 'category'        ).prefetch_related('tags')

6. Consistent Ordering

# Bad: No explicit orderingclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()  # Undefined order! # Good: Explicit orderingclass ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.order_by('-created_at', 'id')    # Stable, consistent ordering

Complete Example

# pagination.pyfrom rest_framework.pagination import PageNumberPagination, CursorPagination class StandardPageNumberPagination(PageNumberPagination):    """Standard page number pagination"""    page_size = 20    page_size_query_param = 'page_size'    max_page_size = 100        def get_paginated_response(self, data):        return Response({            'pagination': {                'count': self.page.paginator.count,                'page': self.page.number,                'pages': self.page.paginator.num_pages,                'page_size': self.get_page_size(self.request),                'links': {                    'next': self.get_next_link(),                    'previous': self.get_previous_link(),                }            },            'results': data        }) class FeedCursorPagination(CursorPagination):    """Cursor pagination for feeds"""    page_size = 20    page_size_query_param = 'page_size'    max_page_size = 100    ordering = '-created_at'        def get_paginated_response(self, data):        return Response({            'pagination': {                'next': self.get_next_link(),                'previous': self.get_previous_link(),            },            'results': data        }) # models.pyclass Article(models.Model):    title = models.CharField(max_length=200)    content = models.TextField()    author = models.ForeignKey(User, on_delete=models.CASCADE)    category = models.ForeignKey(Category, on_delete=models.CASCADE)    status = models.CharField(max_length=20, default='draft')    views = models.IntegerField(default=0)    created_at = models.DateTimeField(auto_now_add=True, db_index=True)    updated_at = models.DateTimeField(auto_now=True)        class Meta:        ordering = ['-created_at', 'id']        indexes = [            models.Index(fields=['-created_at', 'id']),            models.Index(fields=['-views']),            models.Index(fields=['status', '-created_at']),        ] # views.pyfrom django_filters.rest_framework import DjangoFilterBackendfrom rest_framework import filters class ArticleViewSet(viewsets.ModelViewSet):    serializer_class = ArticleSerializer    filter_backends = [        DjangoFilterBackend,        filters.SearchFilter,        filters.OrderingFilter    ]    filterset_class = ArticleFilter    search_fields = ['title', 'content', 'author__username']    ordering_fields = ['created_at', 'views', 'title']    pagination_class = StandardPageNumberPagination        def get_queryset(self):        return Article.objects.select_related(            'author', 'category'        ).prefetch_related('tags')        @action(detail=False, methods=['get'])    def feed(self, request):        """        Real-time feed with cursor pagination        """        self.pagination_class = FeedCursorPagination        return self.list(request) # urls.pyrouter = DefaultRouter()router.register('articles', ArticleViewSet, basename='article') # API Usage:# List with pagination:GET /api/articles/GET /api/articles/?page=2GET /api/articles/?page_size=50 # With filters:GET /api/articles/?status=published&page=2 # With search:GET /api/articles/?search=django&page=1 # With ordering:GET /api/articles/?ordering=-views&page=1 # Feed (cursor pagination):GET /api/articles/feed/GET /api/articles/feed/?cursor=cD0yMDI0... # Disable pagination:GET /api/articles/?paginate=false

Testing Pagination

# tests/test_pagination.pyfrom rest_framework.test import APITestCasefrom myapp.models import Articlefrom django.contrib.auth.models import User class PaginationTest(APITestCase):    def setUp(self):        self.user = User.objects.create_user('user', 'user@test.com', 'pass')                # Create 50 articles        for i in range(50):            Article.objects.create(                title=f'Article {i}',                content=f'Content {i}',                author=self.user,                status='published'            )        def test_default_pagination(self):        """Test default page size"""        response = self.client.get('/api/articles/')        self.assertEqual(response.status_code, 200)        self.assertEqual(len(response.data['results']), 20)        self.assertEqual(response.data['pagination']['count'], 50)        def test_page_2(self):        """Test page 2"""        response = self.client.get('/api/articles/?page=2')        self.assertEqual(response.status_code, 200)        self.assertEqual(len(response.data['results']), 20)        def test_custom_page_size(self):        """Test custom page size"""        response = self.client.get('/api/articles/?page_size=10')        self.assertEqual(response.status_code, 200)        self.assertEqual(len(response.data['results']), 10)        def test_max_page_size(self):        """Test max page size limit"""        response = self.client.get('/api/articles/?page_size=200')        self.assertEqual(response.status_code, 200)        self.assertLessEqual(len(response.data['results']), 100)        def test_pagination_links(self):        """Test next/previous links"""        response = self.client.get('/api/articles/')        self.assertIsNotNone(response.data['pagination']['links']['next'])        self.assertIsNone(response.data['pagination']['links']['previous'])                response = self.client.get('/api/articles/?page=2')        self.assertIsNotNone(response.data['pagination']['links']['next'])        self.assertIsNotNone(response.data['pagination']['links']['previous'])

Tóm Tắt Bài 9.4

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

✅ Pagination Importance:

Why pagination is needed
Benefits over returning all data

✅ PageNumberPagination:

Basic setup
Custom configuration
Custom response format
When to use

✅ LimitOffsetPagination:

Setup and usage
Query parameters
Use cases

✅ CursorPagination:

Why cursor pagination
Configuration
Multiple ordering fields
Use cases

✅ Custom Pagination:

Custom pagination class
Keyset pagination
Header-based pagination
Conditional pagination

✅ Best Practices:

Set max_page_size
Choose appropriate style
Optimize count queries
Add indexes
Use select_related
Consistent ordering

Tổng Kết Series Bài 9

🎉 Chúc mừng! Bạn đã hoàn thành series về Filtering, Searching & Pagination!

Tổng quan những gì đã học:

Bài 9.1: Basic Filtering - DjangoFilterBackend, FilterSets, field lookups
Bài 9.2: Advanced Filtering - Range filters, OrderingFilter, custom backends
Bài 9.3: Searching - SearchFilter, PostgreSQL full-text search, Elasticsearch
Bài 9.4: Pagination - PageNumber, LimitOffset, Cursor pagination, custom styles

Next Steps:

Trong Bài 10, bạn sẽ học về:

File Upload & Download
ImageField và FileField
File validation
Storage backends
Serving files

Navigation:

#api-pagination

Filtering, Searching & Pagination - Phần 4 - Pagination