Quickstart

Use filteralchemy to auto-generate filters based on a SQLAlchemy model:

import flask
from models import Album, session
from webargs.flaskparser import parser
from filteralchemy import FilterSet

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        parser = parser

app = flask.Flask(__name__)

@app.route('/albums')
def get_albums():
    query = AlbumFilterSet().filter()
    return flask.jsonify(query.all())

Customizing operators

By default, filteralchemy generates filters using the Equal operator. To generate filters with different operators, set the operators and column_overrides options in Meta:

from filteralchemy.operators import Greater, Less, Like

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        operators = (Equal, Greater, Less)
        column_overrides = {
            'name': {'operators': (Equal, Like)}
        }

Restricting filtered columns

By default, all columns in the specified model are used to generate filters. To restrict filtered columns, set the fields or exclude options in Meta:

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        fields = ('name', 'genre')

Both fields and exclude can either be a sequence of column names or a callable that receives the FilterSet subclass and returns a sequence of names. filteralchemy provides a helper, index_columns, that restricts fields to indexed columns:

from filteralchemy.utils import index_columns

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        fields = index_columns(engine)

Declaring fields manually

Individual filters can also be declared manually as class variables:

from webargs import fields
from filteralchemy import Filter
from filteralchemy.operators import In, ILike

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        parser = parser
    name = Filter(fields.Str(), operator=ILike)
    genre = Filter(fields.List(fields.Str), operator=In)

Customizing query format

By default, filteralchemy uses two underscores to separate field names and operator names for non-default operators (e.g., “value__gt=5”). Multiple values for the same field are passed using repeated query parameters (e.g., “foo=&foo=2”). To override these defaults, set the formatter and list_class options in Meta:

from webargs.fields import DelimitedList
from filteralchemy.formatters import JsonApiFormatter

class AlbumFilterSet(FilterSet):
    class Meta:
        model = Album
        query = session.query(Album)
        formatter = JsonApiFormatter()
        list_class = DelimitedList

This example implements the JSON API standards for filtering, using parameters like “filter[value][in]=1,2,3”.