pydantic-filters

Define filters as Pydantic models, then translate them into queries with a driver. pydantic-filters also provides reusable pagination and sorting models and a FastAPI integration.

Requirements

• Python 3.10 or newer (including Python 3.14 and 3.15)
• Pydantic 2
• SQLAlchemy 2 or newer when using the SQLAlchemy driver
• FastAPI 0.100 or newer when using the FastAPI plugin

Only Pydantic is installed as a required dependency. Install an integration alongside the package when you need it:

pip install pydantic-filters
pip install "pydantic-filters" "sqlalchemy>=2"
pip install "pydantic-filters" "fastapi>=0.100"

Quick start

Define an SQLAlchemy model and a matching filter:

import sqlalchemy as sa
import sqlalchemy.orm as so

from pydantic_filters import BaseFilter
from pydantic_filters.drivers.sqlalchemy import append_filter_to_statement


class Base(so.DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: so.Mapped[int] = so.mapped_column(primary_key=True)
    name: so.Mapped[str]
    age: so.Mapped[int]


class UserFilter(BaseFilter):
    id: list[int]
    name__ilike: str
    age__ge: int


filter_ = UserFilter(name__ilike="kate", age__ge=18)
statement = append_filter_to_statement(
    statement=sa.select(User),
    model=User,
    filter_=filter_,
)

The resulting statement contains conditions equivalent to:

WHERE users.name ILIKE 'kate' AND users.age >= 18

Fields that were not supplied are ignored. Although filter models inherit from Pydantic's BaseModel, their fields are not required by default.

Where to go next

• Filters: operators, search fields, nested filters, and configuration
• SQLAlchemy: apply filtering, sorting, and pagination to statements
• FastAPI: expose flat query parameters, including nested filters
• Pagination and sorting: built-in and custom models

Source code: github.com/so-saf/pydantic-filters