sqlalchemy-filters

What it is and what it does

sqlalchemy-filters is a query-building library that lets you apply filtering, sorting, and pagination to SQLAlchemy query objects using declarative JSON-like specifications rather than imperative ORM calls. It's designed primarily for REST APIs where clients need to express query constraints as structured data (e.g., from URL parameters or request bodies). The library handles single-model queries, multi-model joins with automatic relationship inference, and hybrid properties, and it can defer field loading to reduce database overhead.

The package depends only on sqlalchemy and six, making it lightweight. It supports Python 3.7, 3.8, 3.9, and 3.10 and has been stable since its first release in 2017, though active maintenance ended in April 2023. The repository remains accessible with a recent commit in January 2025, suggesting the code is not abandoned but receives minimal updates. It carries no known security vulnerabilities.

Use it for:

• Build REST API endpoints that accept filter, sort, and pagination parameters without writing custom query logic for each endpoint.
• Expose database queries to clients safely by translating structured filter specifications into SQLAlchemy operations.
• Restrict database field loads to reduce query overhead when clients request only specific columns via a load specification.
• Filter and sort across related models using automatic joins, allowing clients to query by foreign-key relationships without server-side join configuration.
• Apply hybrid properties and methods as filter and sort targets, enabling computed fields in query constraints.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds filtering, sorting, and pagination capabilities to SQLAlchemy query objects via declarative specifications, designed for REST API exposure.

Yes, if you are building a REST API on SQLAlchemy and need to translate client-supplied filter/sort/pagination parameters into queries. The low install friction, permissive license, and absence of known vulnerabilities make it safe to adopt. However, accept that maintenance is dormant: no updates since April 2023, and compatibility with newer SQLAlchemy versions is unverified. If you require active support or cutting-edge features, evaluate alternatives first.

Install

sqlalchemy-filters on PyPI

pip install sqlalchemy-filters

uv add sqlalchemy-filters

poetry add sqlalchemy-filters

Installing sqlalchemy-filters

Before you install

Low install friction with only two runtime dependencies (sqlalchemy and six). Package is dormant—last release was in April 2023, though the repository remains active with a recent commit in January 2025. Use only if you accept infrequent maintenance.

License in practice

Licensed under Apache License, Version 2.0 (permissive), imposing no restrictions on use or redistribution in proprietary or open-source projects.

Quickstart

pip install sqlalchemy-filters

from sqlalchemy_filters import apply_filters
filter_spec = [{'field': 'name', 'op': '==', 'value': 'example'}]
filtered_query = apply_filters(query, filter_spec)
result = filtered_query.all()

Requires sqlalchemy and Python 3.7 or later; automatic joins depend on sqlalchemy being able to infer foreign-key relationships.

Verify before relying

• Whether the package works with SQLAlchemy 2.0+ (latest major version compatibility not stated in fact sheet)
• Current test coverage and whether dormant status indicates stability or abandonment risk

Package facts

Evidence: sqlalchemy_filters-0.13.0-py3-none-any.whl

Tags

More Python Modules packages