Skip to content

feat: add support for SQLAlchemy func expressions in filter classes - #585

Merged
cofin merged 10 commits into
litestar-org:mainfrom
cofin:feat/issue-519-func-support
Oct 26, 2025
Merged

cofin merged 10 commits into
litestar-org:mainfrom
cofin:feat/issue-519-func-support

Conversation

@cofin

@cofin cofin commented Oct 18, 2025 •

Copy link
Copy Markdown
Member

Summary

Adds support for SQLAlchemy func() expressions in filter classes to eliminate type checker errors when using database functions like func.random() or func.lower().

Closes #519

The Problem

Type checkers currently raise errors when using SQLAlchemy func expressions in filters:

OrderBy(func.random())  # Type error: expected 'str', got 'random'

The field_name parameter was typed as str, but func.random() returns a FunctionElement (subclass of ColumnElement).

The Solution

Updated type signatures to accept Union[str, ColumnElement[Any], InstrumentedAttribute[Any]] in filter classes. The implementation already worked - this just fixes the type annotations.

Key Features

  • Works with all SQLAlchemy func expressions (func.random(), func.lower(), etc.)
  • 100% backward compatible - existing string-based code unchanged
  • Type safe - both mypy and pyright pass in strict mode
  • Supports all 8+ database backends (each has different function names)

Example

from sqlalchemy import func
from advanced_alchemy.filters import OrderBy

# Random ordering
users = await repository.list(OrderBy(func.random()))

# Case-insensitive sorting
users = await repository.list(OrderBy(func.lower(User.name)))

# Backward compatible - still works
users = await repository.list(OrderBy("created_at", sort_order="desc"))

Changes

  • Updated OrderBy, BeforeAfter, OnBeforeAfter, CollectionFilter, NotInCollectionFilter, ComparisonFilter
  • Enhanced _get_instrumented_attr() to handle new types
  • Mock repositories extract field names from InstrumentedAttribute, raise helpful error for func expressions (can't execute SQL in-memory)
  • Added integration tests for func expressions

Note: Different databases use different function names (PostgreSQL: func.random(), MySQL: func.rand(), SQL Server: func.newid()).

@codecov-commenter

codecov-commenter commented Oct 19, 2025 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 40.90909% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.26%. Comparing base (223c3f6) to head (536f81e).
⚠️ Report is 71 commits behind head on main.

Files with missing lines Patch % Lines
advanced_alchemy/repository/memory/_async.py 13.33% 13 Missing ⚠️
advanced_alchemy/repository/memory/_sync.py 13.33% 13 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #585      +/-   ##
==========================================
- Coverage   79.48%   79.26%   -0.23%     
==========================================
  Files          87       87              
  Lines        6346     6355       +9     
  Branches      807      810       +3     
==========================================
- Hits         5044     5037       -7     
- Misses       1051     1068      +17     
+ Partials      251      250       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@cofin
cofin force-pushed the feat/issue-519-func-support branch from 568733e to b9fa255 Compare October 24, 2025 13:46
cofin added 7 commits October 24, 2025 10:19
Add support for SQLAlchemy func() expressions (e.g., func.random(), func.lower())
in filter classes to eliminate type checker errors when using database functions.

Changes:
- Update field_name type to Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]
  in OrderBy, BeforeAfter, OnBeforeAfter, CollectionFilter, NotInCollectionFilter,
  and ComparisonFilter classes
- Update _get_instrumented_attr() to handle ColumnElement and InstrumentedAttribute
- Add comprehensive docstrings with examples for func expressions
- Update mock repository methods to extract field names from InstrumentedAttribute
- Add integration tests for func.random(), func.lower(), and InstrumentedAttribute

Type Safety:
- Both mypy 1.18.2 and pyright 1.1.406 pass in strict mode
- No loss of type specificity - Union preserves full type information
- ColumnOperators is common base type for both ColumnElement and InstrumentedAttribute

Backward Compatibility:
- All existing string-based usage continues to work
- InstrumentedAttribute (Model.field) usage unchanged
- Framework integrations (Litestar, FastAPI) work without changes
- All existing tests pass

Database Support:
- PostgreSQL: func.random(), func.lower()
- MySQL: func.rand() (different name)
- SQLite: func.random()
- SQL Server: func.newid()
- Oracle: func.dbms_random.value()
- All 8+ supported databases work

Issue: litestar-org#519
… instance methods

Convert _extract_field_name, _filter_in_collection, _filter_not_in_collection,
_filter_on_datetime_field, and _order_by from @staticmethod to instance methods.

This improves code clarity by using self._extract_field_name() instead of
SQLAlchemyAsyncMockRepository._extract_field_name(), making the code more
maintainable and following standard Python patterns for helper methods.
…data

- Skip Oracle databases in test_order_by_with_func_random (uses dbms_random.value() instead of random())
- Replace 'The Matrix' with 'The Godfather' in test data to match test assertions
- Update test_before_after_filter to expect 2 results (both movies before 1999)
- Update test_on_before_after_filter to expect 1 result (only The Hangover after 1999)
Reverted the previous change that replaced 'The Matrix' with 'The Godfather' because
it broke 40+ other tests that depend on the same test data.

Instead, updated only the specific test assertions:
- test_order_by_with_func_lower: Updated to expect alphabetical order with 'The Matrix'
  (Shawshank Redemption, The Hangover, The Matrix)
- test_before_after_filter: Reverted to expect 1 result (only Shawshank before 1999-03-31)
- test_on_before_after_filter: Reverted to expect 2 results (Matrix and Hangover on/after 1999-03-31)
- test_order_by_with_func_random: Kept Oracle skip for dbms_random.value() compatibility

All filter tests now pass on SQLite and other databases.
@cofin
cofin force-pushed the feat/issue-519-func-support branch from b9fa255 to bbd8e80 Compare October 24, 2025 15:19
@cofin
cofin merged commit 05a413b into litestar-org:main Oct 26, 2025
1 check passed
@github-actions

Copy link
Copy Markdown

Documentation preview will be available shortly at https://litestar-org.github.io/advanced-alchemy-docs-preview/585

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Enhancement: add support for sqlalchemy.func type

3 participants