ドキュメント価格ブログ
お問い合わせ
ログイン無料で新規登録
Back to Tech Articles

DRFとFastAPIで多様なページネーション戦略を実装する

Sep 19, 2025
# Misc

Emily Parker

Product Engineer · Leapcell

この記事はEnglish、한국어、Deutschでも利用できます
Cover of "DRFとFastAPIで多様なページネーション戦略を実装する"

はじめに：効率的なページネーションによる大規模データセットのナビゲーション

現代のWeb開発では、膨大な量のデータを扱うことは一般的な課題です。APIを通じてリソースのコレクションを公開する場合、単一のレスポンスでデータセット全体を返すことは、不可能ではないにせよ、しばしば非現実的です。そのようなアプローチは、応答時間の遅延、サーバーとクライアント双方での過剰なメモリ消費、そしてユーザーエクスペリエンスの低下につながる可能性があります。ページネーションは、クライアントがデータを管理可能なチャンクで取得できるようにする、不可欠なソリューションとして登場します。データをページに分割するという概念は単純に見えますが、異なるページネーション戦略は、さまざまなユースケースに対応する、それぞれ異なる利点と欠点を提供します。この記事では、2つの著名なページネーションテクニック、すなわちLimit/Offsetとカーソルベースのページネーションを探り、2つの人気のあるPython Webフレームワーク、Django Rest Framework (DRF)とFastAPI内での実装方法をデモンストレーションします。これらの方法を理解することは、大規模データセットを効果的に提供できる、スケーラブルで堅牢なAPIを構築するために不可欠です。

コアページネーションの概念：入門

実装の詳細に入る前に、ページネーション戦略の根底にある基本的な概念を明確にしましょう。

  • ページネーション (Pagination): 大規模なデータセットを、小さく個別のページまたはチャンクに分割し、クライアントに順番に提供するプロセス。これにより、パフォーマンスが向上し、リソース使用量が管理されます。
  • ページ (Page): 総データセットの一部であり、通常はサイズ（1ページあたりのアイテム数）と識別子（ページ番号、オフセット、またはカーソル）によって定義されます。
  • リミット (Limit): 単一のレスポンスで返されるアイテムの最大数（つまり、ページサイズ）を指します。
  • オフセット (Offset): 結果の返却を開始する前に、データセットの先頭からスキップするアイテム数を示します。
  • カーソル (Cursor): データセット内の特定のアイテムを指す、不透明な文字列または値。これは、絶対的な位置（オフセットのような）に依存せずに、「次」または「前」のアイテムセットを取得するためのブックマークとして使用されます。
  • 安定したページネーション (Stable Pagination): クライアントがページネーション中にデータセットにアイテムが追加または削除されても、アイテムがスキップされたりページ間で重複したりしない場合、ページネーション戦略は安定していると見なされます。

Limit/Offsetページネーション：シンプルさとその落とし穴

Limit/Offsetは、おそらく最も一般的で直感的なページネーション戦略です。これは、limit（返されるアイテム数）とoffset（スキップするアイテム数）の2つのパラメータを指定することによって機能します。

仕組み：

クライアントは limit と offset を提供してデータを要求します。サーバーは、 offset 番目のレコードから開始して limit 個のアイテムを取得します。たとえば、1ページあたり10アイテムで2ページ目を取得するには、クライアントは limit=10&offset=10 を要求します。

利点：

  • シンプルさ： サーバーとクライアントの両方にとって、理解と実装が容易です。
  • 直接アクセス： クライアントは、 offset を計算することによって、任意の特定のページに簡単にジャンプできます（ offset = (page_number - 1) * limit ）。

欠点：

  • 大きなオフセットでのパフォーマンス低下： offset が増加するにつれて、データベースはスキップされたレコード全体をスキャンする必要がある場合があり、特に適切なインデックスがない大規模なテーブルでは、パフォーマンスのボトルネックにつながります。
  • 不安定性（スキップ/重複アイテム）： クライアントがページネーション中に、現在のオフセットより前にデータセットにアイテムが追加または削除された場合、結果は一貫性を欠く可能性があります。アイテムが2つのページに表示されたり、完全にスキップされたりすることがあります。製品リストを考えてみましょう。ユーザーが5ページ目にいる間にリストの先頭に新しい製品が追加された場合、後続のページには既に表示されたアイテムが含まれていたり、新しいアイテムがスキップされたりする可能性があります。

DRFでのLimit/Offsetの実装

DRFは組み込みの LimitOffsetPagination クラスを提供しており、実装を容易にします。

# project/settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 10 # デフォルトのページサイズ
}

# app/views.py
from rest_framework import generics
from .models import Product
from .serializers import ProductSerializer

class ProductListView(generics.ListAPIView):
    queryset = Product.objects.all().order_by('id') # 一貫したページネーションのために常に注文する
    serializer_class = ProductSerializer
    # pagination_class = LimitOffsetPagination # ビューごとに設定することも可能

クライアントは次に /products/?limit=5&offset=10 のようなリクエストを行います。 limit を省略すると、デフォルトの PAGE_SIZE を使用できます。

FastAPIでのLimit/Offsetの実装

FastAPIは、よりミニマリストなフレームワークであるため、Pydanticと依存関係を活用して、もう少し手動でのセットアップが必要です。

# main.py
from typing import List, Optional
from fastapi import FastAPI, Depends, Query
from pydantic import BaseModel
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session

# データベース設定（例として簡略化）
DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class ProductModel(Base):
    __tablename__ = "products"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    description = Column(String)

Base.metadata.create_all(bind=engine)

class ProductCreate(BaseModel):
    name: str
    description: str

class Product(ProductCreate):
    id: int

    class Config:
        orm_mode = True

app = FastAPI()

# DBセッションを取得するための依存関係
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# LimitOffsetページネーション依存関係
class LimitOffsetParams:
    def __init__(
        self,
        limit: int = Query(10, ge=1, le=100),
        offset: int = Query(0, ge=0),
    ):
        self.limit = limit
        self.offset = offset

@app.post("/products/", response_model=Product)
def create_product(product: ProductCreate, db: Session = Depends(get_db)):
    db_product = ProductModel(**product.dict())
    db.add(db_product)
    db.commit()
    db.refresh(db_product)
    return db_product

@app.get("/products/", response_model=List[Product])
def get_products(
    pagination: LimitOffsetParams = Depends(),
    db: Session = Depends(get_db)
):
    products = db.query(ProductModel).offset(pagination.offset).limit(pagination.limit).all()
    return products

このFastAPIの例では、LimitOffsetParamsが、 limit および offset パラメータをルート関数に直接注入する依存関係として機能します。SQLクエリは次に、データを取得するために .offset() および .limit() を使用します。

カーソルベースページネーション：安定性とパフォーマンスの確保

カーソルベースページネーション（キーセットページネーションとも呼ばれる）は、特に大規模データセットにおいて、Limit/Offsetの安定性とパフォーマンスの問題に対処します。数値オフセットを使用する代わりに、最後のアイテムのポインタ（カーソル）を使用して次の結果セットを取得します。

仕組み：

クライアントは、ページネーションされたデータとともにカーソル値（エンコードされた識別子：IDやタイムスタンプなど）を受け取ります。次のページを取得するために、クライアントはこのカーソルをサーバーに送り返し、サーバーはカーソル値の 後 のアイテムを取得します。これは、一貫してソートされたデータに大きく依存します。たとえば、ID X の後のアイテムを取得するには、クエリは WHERE id > X ORDER BY id LIMIT N となります。

利点：

  • 安定性： ページネーション中にアイテムが追加または削除されても、ソート順が一貫している限り、後続のページに含まれるアイテムには影響しません。これにより、レコードのスキップや重複が防止されます。
  • パフォーマンス： データベースは、ソートされた列（例： id または timestamp ）のインデックスを効率的に使用して、開始点をすばやく見つけることができます。これにより、大きなオフセットに関連する遅いスキャンが回避されます。これは、非常に大規模なデータセットに対してはるかにうまくスケーリングします。
  • スケーラビリティ： ユーザーが通常一度に1ページずつのみ前後に移動する、無限スクロールフィードやタイムラインに適しています。

欠点：

  • 直接ページアクセス不可： 数値ページ概念がないため、クライアントは任意のページ（例：5ページ目）に「ジャンプ」できません。現在地からの相対的な移動のみが可能です。
  • 安定したソートキーが必要： カーソルとして機能する、一意で不変で順序付け可能な列（主キーやタイムスタンプなど）が必要です。
  • 後方ページネーションの複雑さ： 後方ページネーション（例：「前のページ」）の実装は、ソートとフィルタリング条件を反転するための追加ロジックが必要なため、より複雑になる可能性があります。

DRFでのカーソルベースページネーションの実装

DRFは CursorPagination を提供しており、カーソル値のエンコード/デコードをスマートに処理します。

# project/settings.py
# デフォルトとして使用したい場合
# REST_FRAMEWORK = {
#     'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
#     'PAGE_SIZE': 10,
#     'CURSOR_PAGINATION_USE_REL_LINK_HEADERS': True # オプション、HATEOASリンク用
# }

# app/views.py
from rest_framework import generics
from rest_framework.pagination import CursorPagination
from .models import Product
from .serializers import ProductSerializer

# 特定の順序付けのためのカスタムカーソルページネーション
class ProductCursorPagination(CursorPagination):
    page_size = 10
    ordering = 'created_at' # または 'id', 'name' など。一意で一貫してソートされている必要がある
    # cursor_query_param = 'cursor' # デフォルト、変更可能
    # page_size_query_param = 'page_size' # デフォルト、変更可能

class ProductListView(generics.ListAPIView):
    queryset = Product.objects.all().order_by('created_at', 'id') # 安定性のために重要
    serializer_class = ProductSerializer
    pagination_class = ProductCursorPagination

ProductCursorPagination の ordering 属性は非常に重要です。これは、カーソルに使用される列と必要なソート順を定義します。プライマリソートフィールド（例： created_at ）がユニークでない場合に対応するために、セカンダリユニークフィールド（例： id ）を ordering に含めることは、しばしば良い習慣です。 リクエストは、前のレスポンスで提供された不透明なカーソル文字列 AbcD... を使用して、次のページの場合は /products/?cursor=AbcD... のようになります。

FastAPIでのカーソルベースページネーションの実装

FastAPIでカーソルベースページネーションを実装するには、カスタム依存関係とクエリロジックの慎重な処理が必要です。

# main.py (以前のFastAPI例を基にする)
import base64
from typing import List, Optional
from fastapi import FastAPI, Depends, Query, HTTPException
from pydantic import BaseModel, Field
from sqlalchemy import create_engine, Column, Integer, String, DateTime
from sqlalchemy.sql import func
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
from datetime import datetime

# (データベース設定とProductModel/ProductCreate/Productは以前と同じ)
class ProductModel(Base):
    __tablename__ = "products"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    description = Column(String)
    created_at = Column(DateTime, default=func.now()) # カーソルページネーションのために追加

Base.metadata.create_all(bind=engine)

class Product(BaseModel):
    id: int
    name: str
    description: str
    created_at: datetime # レスポンスにcreated_atを含める

    class Config:
        orm_mode = True

app = FastAPI()

# (get_db関数は同じ)

class CursorParams:
    def __init__(
        self,
        limit: int = Query(10, ge=1, le=100),
        after_cursor: Optional[str] = Query(None, description="次のページ用のカーソル"),
    ):
        self.limit = limit
        self.after_cursor = after_cursor

def decode_cursor(encoded_cursor: str) -> tuple[datetime, int]:
    try:
        decoded_string = base64.b64decode(encoded_cursor).decode('utf-8')
        timestamp_str, item_id_str = decoded_string.split(":")
        return datetime.fromisoformat(timestamp_str), int(item_id_str)
    except (ValueError, TypeError) as e:
        raise HTTPException(status_code=400, detail=f"無効なカーソル形式: {e}")

def encode_cursor(created_at: datetime, item_id: int) -> str:
    cursor_string = f"{created_at.isoformat()}:{item_id}"
    return base64.b64encode(cursor_string.encode('utf-8')).decode('utf-8')

@app.post("/products/", response_model=Product)
def create_product(product: ProductCreate, db: Session = Depends(get_db)):
    db_product = ProductModel(**product.dict())
    db.add(db_product)
    db.commit()
    db.refresh(db_product)
    return db_product

@app.get("/products_cursor/", response_model=List[Product])
def get_products_cursor(
    pagination: CursorParams = Depends(),
    db: Session = Depends(get_db)
):
    query = db.query(ProductModel)
    
    if pagination.after_cursor:
        last_created_at, last_id = decode_cursor(pagination.after_cursor)
        # created_atのタイを処理：created_atが同じ場合、idでタイを破る
        query = query.filter(
            (ProductModel.created_at > last_created_at) |
            ((ProductModel.created_at == last_created_at) & (ProductModel.id > last_id))
        )

    products = query.order_by(ProductModel.created_at, ProductModel.id).limit(pagination.limit + 1).all() # 次のページがあるかどうかを判断するために1つ余分に取得
    
    has_next_page = len(products) > pagination.limit
    
    if has_next_page:
        products_to_return = products[:pagination.limit]
        last_product = products_to_return[-1]
        next_cursor = encode_cursor(last_product.created_at, last_product.id)
    else:
        products_to_return = products
        next_cursor = None

    # 通常、データとnext_cursorを一緒に返します。例：辞書で
    return {
        "products": products_to_return,
        "next_cursor": next_cursor
    }

このFastAPIの例では、CursorParamsが limit および after_cursor をルートに注入します。透明なカーソル値を管理するために decode_cursor と encode_cursor 関数を定義します。データベースクエリは、 created_at と id で順序付けられており、 created_at の値が同じ場合でも一貫した安定したページネーションを保証するために、デコードされたカーソル値の「後」のアイテムを具体的にフィルタリングします。 next_cursor を提供するかどうかを簡単に判断するために、 limit + 1 個のアイテムを取得します。

適切な戦略の選択

Limit/Offsetとカーソルベースページネーションの選択は、アプリケーションの要件に大きく依存します：

  • Limit/Offsetを使用する場合：

    • データセットサイズが比較的小さい、または中間程度の場合。
    • クライアントが任意のページにジャンプする必要がある場合（例：「10ページ中1ページ」を表示）。
    • データの更新がまれであるか、ページネーション全体での一貫性がそれほど重要でない場合。
    • 実装のシンプルさが優先される場合。

  • カーソルベースページネーションを使用する場合：

    • 非常に大規模で、頻繁に更新される、または急速に成長するデータセットを扱っている場合。
    • ページネーション全体での安定性と一貫した結果が非常に重要な場合（例：ソーシャルメディアフィード、イベントログ）。
    • スケーラビリティにおけるパフォーマンスが主要な懸念事項である場合。
    • クライアントが主に一度に前後に移動する場合（例：「さらに読み込み」機能）。

結論：APIのニーズに合わせてページネーションを調整する

効果的なページネーションは、大量のデータを扱う適切に設計されたAPIの礎です。Limit/Offsetページネーションはシンプルさと直接的なページアクセスを提供しますが、大規模でのパフォーマンスと安定性の問題に苦しむ可能性があります。カーソルベースページネーションは、実装がやや複雑ですが、一貫したソート順と「最後に見た」ポインタに依存することで、大規模で動的なデータセットに対して優れたパフォーマンスと安定性を提供します。データの特徴とクライアントのナビゲーションパターンを慎重に評価することにより、最も適切なページネーション戦略を選択し、パフォーマンスと信頼性の高いAPIエクスペリエンスを保証できます。鍵は、トレードオフを理解し、選択された方法を特定のアプリケーションの需要と一致させることです。

Share this article

HackerNews

More Posts from Leapcell

cover

Pythonディスクリプタの深掘り：Django ORMとそれ以降を強化する

cover

Python APScheduler vs Celery Beat におけるタスクスケジューリング

Popular Posts