Introduction

fastapi-filters is a library that provides filtering/sorting feature for FastAPI applications.

---

Installation

pip install fastapi-filters

Quickstart

Define filters using a FilterSet class:

from fastapi import Depends, FastAPI
from pydantic import BaseModel

from fastapi_filters import FilterField, FilterSet, SortingValues, create_sorting

app = FastAPI()


class UserOut(BaseModel):
    name: str
    surname: str
    age: int


class UserFilters(FilterSet):
    name: FilterField[str]
    surname: FilterField[str]
    age: FilterField[int]


@app.get("/users")
async def get_users(
    filters: UserFilters = Depends(),
    sorting: SortingValues = Depends(create_sorting("name", "age")),
) -> list[UserOut]:
    pass

Query parameters are auto-generated based on field types:

GET /users?name[eq]=Steve&age[gt]=30&sort=+age

fastapi-filters supports SQLAlchemy, Tortoise ORM, Beanie (MongoDB), and raw SQL integrations.

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from fastapi_filters.ext.sqlalchemy import apply_filters_and_sorting


@app.get("/users")
async def get_users(
    db: AsyncSession = Depends(get_db),
    filters: UserFilters = Depends(),
    sorting: SortingValues = Depends(create_sorting("name", "age")),
) -> list[UserOut]:
    stmt = apply_filters_and_sorting(select(User), filters, sorting)
    return (await db.scalars(stmt)).all()