[sqladmin-912] - Add perform context functions, DateRange filter, JSON export, and other tweaks...

[sergei-vasilev-dev]

#912

I think better to perform template context on the model level. Please, take a look and say what you think.
Thanks!

[aminalaee]

Hey @sergey-vasiliev-dualboot ,
I think this is nice, Can you please update the docs and explain the example use-case there?

[mmzeynalli]

@sergey-vasiliev-dualboot it is nice addition, any updates? This is related to my issue #942

[sergei-vasilev-dev]

Hi! @mmzeynalli, plan to update till the end of this week.

[mmzeynalli]

Okay, let us know when it is ready to be reviewed

[sergei-vasilev-dev]

Enhanced Filtering System and ModelView Improvements

Summary

This PR introduces significant enhancements to SQLAdmin's filtering capabilities and query optimization. All changes are fully backward compatible and extend existing functionality without breaking changes.

🎯 New Features

Advanced Filter Types

1. UniqueValuesFilter (Enhanced)

Improved version with support for numeric types and custom formatting:

• ✅ Integer and Float column support
• ✅ Custom value display with lookups_ui_method
• ✅ Float rounding with float_round_method
• ✅ Custom ordering with lookups_order
• ✅ Multiple value selection

from sqladmin.filters import UniqueValuesFilter
import math

UniqueValuesFilter(
    Product.price,
    lookups_ui_method=lambda v: f"${v:.2f}",
    float_round_method=lambda v: math.floor(v),
    lookups_order=Product.price
)

2. ManyToManyFilter (NEW)

Filter through many-to-many relationships using junction tables:

from sqladmin.filters import ManyToManyFilter

ManyToManyFilter(
    column=User.id,
    link_model=UserRole,
    local_field="user_id",
    foreign_field="role_id",
    foreign_model=Role,
    foreign_display_field=Role.name
)

3. RelatedModelFilter (NEW)

Filter by columns in related models through automatic JOIN:

from sqladmin.filters import RelatedModelFilter

RelatedModelFilter(
    column=User.address,
    foreign_column=Address.city,
    foreign_model=Address
)

4. DateRangeFilter (NEW)

Filter by date/datetime ranges with start and end values:

from sqladmin.filters import DateRangeFilter

DateRangeFilter(
    Order.created_at,
    title="Order Date"
)

5. Enhanced ForeignKeyFilter

Now supports multiple value selection and custom ordering:

ForeignKeyFilter(
    Product.category_id,
    Category.name,
    foreign_model=Category,
    lookups_order=Category.name  # NEW: Sort alphabetically
)

ModelView Query Optimization

_safe_join()

Prevents duplicate JOINs in complex queries with related models:

• Automatically used in search_query() and sort_query()
• Significantly improves query performance
• No configuration needed - works automatically

add_relation_loads()

Optimizes relationship loading using selectinload:

• Reduces N+1 query problems
• Automatically applied in list() and get_model_objects()
• Works transparently

async_search_query()

Optional async search for custom implementations:

class UserAdmin(ModelView, model=User):
    async_search = True
    
    async def async_search_query(self, stmt, term, request):
        # Custom async search logic
        return stmt.filter(...)

Pretty Export Enhancements

JSON Export with Formatting

Pretty export now supports JSON format:

• Applies column labels as keys
• Uses custom formatters
• Maintains all formatting logic

class OrderAdmin(ModelView, model=Order):
    use_pretty_export = True
    export_types = ["csv", "json"]

Better Relation Handling

• Support for related_model_relations attribute
• Improved list handling in related fields

📊 Testing

Test Coverage

• ✅ 248 tests passing (added 18 new tests)
• ✅ All existing tests still pass
• ✅ No regression issues

New Tests Added

• test_unique_values_filter_* (6 tests)
• test_many_to_many_filter_* (2 tests)
• test_related_model_filter_* (1 test)
• test_date_range_filter_* (2 tests)
• test_safe_join_* (2 tests)
• test_add_relation_loads (1 test)
• test_async_search_query_* (1 test)
• test_*_uses_safe_join (2 tests)
• test_pretty_export_json_* (1 test)

📚 Documentation

New Documentation

• ✅ docs/cookbook/advanced_filtering.md - Comprehensive filtering guide with examples
• ✅ docs/cookbook/readonly_views.md - Read-only view patterns and best practices

Updated Documentation

• ✅ docs/configurations.md - Added "Advanced Filters" and "Async Search" sections
• ✅ docs/working_with_templates.md - Examples for perform_*_context methods
• ✅ README.md - Mentioned advanced filtering capabilities

🔧 Code Quality

• ✅ Linter checks pass (ruff)
• ✅ Type checking passes (mypy)
• ✅ Code formatted per project standards
• ✅ All docstrings concise and meaningful
• ✅ No imports inside functions

⚠️ Breaking Changes

None! All changes are fully backward compatible:

• New methods are optional
• New attributes have sensible defaults
• Existing API unchanged
• All existing code works without modification

🔄 Migration Guide

No migration needed! Simply start using new features:

from sqladmin import ModelView
from sqladmin.filters import UniqueValuesFilter, ManyToManyFilter

class MyAdmin(ModelView, model=MyModel):
    column_filters = [
        UniqueValuesFilter(MyModel.price),  # Just use it!
        ManyToManyFilter(...)  # Works alongside existing filters
    ]

📈 Performance Impact

Improvements

• ✅ Safe JOIN - Prevents duplicate JOINs that slow down queries
• ✅ Relation Loading - Eliminates N+1 query problems
• ✅ Zero overhead - New features are opt-in only

No Negative Impact

• Default behavior unchanged
• Existing queries maintain same performance
• No additional dependencies

🎯 Use Cases

E-commerce Platform

class ProductAdmin(ModelView, model=Product):
    column_filters = [
        UniqueValuesFilter(Product.price, lookups_ui_method=lambda v: f"${v:.2f}"),
        ManyToManyFilter(...),  # Filter by tags
        RelatedModelFilter(...),  # Filter by supplier country
        DateRangeFilter(Product.created_at)
    ]

Analytics Dashboard

class OrderAdmin(ModelView, model=Order):
    async_search = True
    use_pretty_export = True
    export_types = ["csv", "json"]

📝 Implementation Details

Files Modified

• sqladmin/filters.py (+265 lines)
• sqladmin/models.py (+82 lines)
• sqladmin/pretty_export.py (+38 lines)
• sqladmin/application.py (+8 lines)
• tests/ (+272 lines)

✅ Checklist

• Code follows project style guidelines
• All tests pass (248 passing)
• Linter checks pass
• Type checking passes
• Documentation updated
• Backward compatibility maintained
• No breaking changes
• Examples provided in docs
• Self-documenting code with minimal docstrings

🚀 Ready for Review

This PR has been thoroughly tested and documented. All changes maintain backward compatibility while significantly extending SQLAdmin's filtering and query optimization capabilities.

---

Looking forward to feedback!

[sergei-vasilev-dev]

I just want to mention that we performed a library for one of our projects, and it turned out that the code here was collected from several different PRs. But it is all covered by tests, so it might make sense to consider it as the main one.

[rusanpas]

This seems like a great improvement, but I have a question.

Shouldn't the filters be accompanied by changes to the templates?

The date filter, without modifying the template to add, for example, a Flatpickr (range), would leave the filter incomplete unless a custom template is created, right?

[sergei-vasilev-dev]

You're right. I forgot to add template updates.

[mmzeynalli]

Maybe:

def _get_filter_value(values_list: list[str], column_type: Any) -> list:
    """Convert list of string values to appropriate types based on column type."""
    if isinstance(column_type, Integer):
        conv = int
    elif isinstance(column_type, Float):
        conv = float
    else:
        conv = lambda x: x

    return [conv(item) for item in values_list]

[mmzeynalli]

can this be multiple? like [Model.count, Model.created_at]

[mmzeynalli]

value == "" is covered by not value. So, change pls:

if not value or value == [""]

[mmzeynalli]

maybe create another method for lookup generation. And use similar method that I suggested above

[mmzeynalli]

replace with getattr(filter, 'has_date_filter', False)

[mmzeynalli]

dont now if getattr works here

[mmzeynalli]

Consider adding this to different file. There is nice PR by @fd-oncodna which will clean this part

[mmzeynalli]

Why selectinload instead of joinedload? Any specific reason?

[mmzeynalli]

Remove everything related to pretty_export: this was added with #938

[mmzeynalli]

maybe test if results indeed shows results 25 and 30.

[mmzeynalli]

Just curious: Do you think current design would support RangeFilter to other types as well? Let's say, I want all users between age 20 and 30. Or filter range of ForeignKey values (20 < User.profile.age < 30).

[mmzeynalli]

@sergei-vasilev-dev any updates?