https://github.com/sqlalchemy-filterset/sqlalchemy-filterset
SQLAlchemy Filterset. An easy way to filter, sort, paginate SQLAlchemy queries
https://github.com/sqlalchemy-filterset/sqlalchemy-filterset
aiohttp fastapi fastapi-filters fastapi-sqlalchemy filter filterset flask-filter flask-sqlalchemy orm python python-sql-filter query-builder sql sqlalchemy sqlalchemy-filter sqlalchemy-filters-plus sqlalchemy-filterset sqlalchemy-query-builder sqlalchemy-query-filter
Last synced: 28 days ago
JSON representation
SQLAlchemy Filterset. An easy way to filter, sort, paginate SQLAlchemy queries
- Host: GitHub
- URL: https://github.com/sqlalchemy-filterset/sqlalchemy-filterset
- Owner: sqlalchemy-filterset
- License: mit
- Created: 2023-01-05T08:34:29.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-27T18:13:31.000Z (over 1 year ago)
- Last Synced: 2025-09-22T05:37:03.310Z (about 2 months ago)
- Topics: aiohttp, fastapi, fastapi-filters, fastapi-sqlalchemy, filter, filterset, flask-filter, flask-sqlalchemy, orm, python, python-sql-filter, query-builder, sql, sqlalchemy, sqlalchemy-filter, sqlalchemy-filters-plus, sqlalchemy-filterset, sqlalchemy-query-builder, sqlalchemy-query-filter
- Language: Python
- Homepage:
- Size: 808 KB
- Stars: 55
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- License: LICENSE.md
Awesome Lists containing this project
README
SQLAlchemy Filterset
An easy way to filter, sort, paginate SQLAlchemy queries
[](https://codecov.io/gh/sqlalchemy-filterset/sqlalchemy-filterset)
[](https://badge.fury.io/py/sqlalchemy-filterset)
[](https://pepy.tech/project/sqlalchemy-filterset)
[](https://github.com/sqlalchemy-filterset/sqlalchemy-filterset/actions/workflows/codeql.yml)
---
**Documentation**: https://sqlalchemy-filterset.github.io/sqlalchemy-filterset
**Source Code**: https://github.com/sqlalchemy-filterset/sqlalchemy-filterset
---
The library provides a convenient and organized way to filter your database records.
By creating a `FilterSet` class, you can declaratively define the filters you want to apply to your `SQLAlchemy` queries.
This library is particularly useful in web applications, as it allows users to easily search, filter, sort, and paginate data.
The key features are:
* [X] Declarative definition of filters.
* [X] Keeping all of your filters in one place, making it easier to maintain and change them as needed.
* [X] Constructing complex filtering conditions by combining multiple simple filters.
* [X] Offer of a standard approach to writing database queries.
* [X] Reduction of code duplication by reusing the same filters in multiple places in your code.
* [X] Sync and Async support of modern SQLAlchemy.
## Installation
```bash
pip install sqlalchemy-filterset
```
Requirements: `Python 3.7+` `SQLAlchemy 2.0+`
## Basic FilterSet and Filters Usage
In this example we specify criteria for filtering the database records
by simply setting the attributes of the `ProductFilterSet` class.
This is more convenient and easier to understand than writing raw SQL queries, which
can be more error-prone and difficult to maintain.
### Define a FilterSet
```python
from sqlalchemy_filterset import BaseFilterSet, Filter, RangeFilter, BooleanFilter
from myapp.models import Product
class ProductFilterSet(BaseFilterSet):
id = Filter(Product.id)
price = RangeFilter(Product.price)
is_active = BooleanFilter(Product.is_active)
```
### Define a FilterSchema
```python
import uuid
from pydantic import BaseModel
class ProductFilterSchema(BaseModel):
id: uuid.UUID | None
price: tuple[float, float] | None
is_active: bool | None
```
### Usage
```python
# Connect to the database
engine = create_engine("postgresql://user:password@host/database")
Base.metadata.create_all(bind=engine)
SessionLocal = sessionmaker(bind=engine)
session = SessionLocal()
# Define sqlalchemy query
query = select(Product)
# Define parameters for filtering
filter_params = ProductFilterSchema(price=(10, 100), is_active=True)
# Create the filterset object
filter_set = ProductFilterSet(query)
# Apply the filters to the query
query = filter_set.filter_query(filter_params.dict(exclude_unset=True))
# Execute the query
session.execute(query).unique().scalars().all()
```
This example will generate the following query:
```sql
select product.id, product.title, product.price, product.is_active
from product
where product.price >= 10
and product.price <= 100
and product.is_active = true;
```
## License
This project is licensed under the terms of the MIT license.
## Supported by
