fastapi-filter

You can filter on related models by nesting filter classes and using the with_prefix utility.

To make this work in your database query, you must ensure your query performs a join (e.g., .outerjoin()) with the related model.

with_prefix(prefix, filter_class) creates a new filter instance where all fields from the filter_class are prefixed with the provided prefix. This allows you to use query parameters like ?prefix__field=value.

from typing import Optional

class AddressFilter(Filter):
    street: Optional[str]
    country: Optional[str]
    city__in: Optional[list[str]]

    class Constants(Filter.Constants):
        model = Address

class UserFilter(Filter):
    name: Optional[str]
    address: Optional[AddressFilter] = FilterDepends(with_prefix("address", AddressFilter))

    class Constants(Filter.Constants):
        model = User

@app.get("/users", response_model=list[UserOut])
async def get_users(user_filter: UserFilter = FilterDepends(UserFilter), db: AsyncSession = Depends(get_db)) -> Any:
    # You MUST join the related model to filter on it
    query = user_filter.filter(select(User).outerjoin(Address))
    result = await db.execute(query)
    return result.scalars().all()

To enable ordering in your API, add an order_by field to your filter class. By default, this field accepts a list of strings.

Usage Patterns:

• Query Parameter: Pass a comma-separated list of strings: ?order_by=age,-created_at.
• Direction: Prefix a field with - for descending order or + for ascending order (default). Example: -name or +id.

Customization:

• Rename the field: Set ordering_field_name in the Constants class to use a different name in the query string.
• Restrict fields: Use a Pydantic field_validator on the order_by field to ensure users only sort by allowed columns.

class UserFilter(Filter):
    class Constants(Filter.Constants):
        model = User
        ordering_field_name = "custom_order_by"

    custom_order_by: Optional[list[str]]

# Usage in endpoint:
# query = user_filter.sort(query)

# Valid URL:
# /users?custom_order_by=age,-created_at

To enable text searching, add a search field to your filter class.

Configuration Requirements:

1. Field Name: The default is search, but you can override this by setting search_field_name in the Constants class.
2. Target Fields: You must define which model columns/fields should be searched by setting search_model_fields (a list of strings) in the Constants class.

Usage:

• Pass a single string via the query parameter: ?search=Johnny or ?custom_name_for_search=Johnny.

class UserFilter(Filter):
    class Constants(Filter.Constants):
        model = User
        search_field_name = "custom_name_for_search"
        search_model_fields = ["name", "email"]

@app.get("/users")
async def get_users(user_filter: UserFilter = FilterDepends(UserFilter)):
    query = select(User)
    query = user_filter.sort(query) # Note: sort() is used to apply the search/order logic to the query
    ...