Installation

pip install django-rql-filter

Usage

Add rql_filter to your project INSTALLED_APPS.

Add the RQLFilterBackend to your viewset filter_backends:

from rql_filter.backend import RQLFilterBackend

class ThingyViewSet(viewsets.ReadOnlyModelViewSet):
    filter_backends = (
        ...
        RQLFilterBackend,
        ...
    )

You may now pass a RQL/RSQL/FIQL query to API URLs using the q querystring parameter:

curl http://my.app/api/thingies/?format=json&q=name==bob;age=gt=30

Query syntax

A query is made using a combination of field comparisons. Comparisons are composed by a field name, an operator and a value.

Comparisons can traverse model relations by separating field names with a double underscore: father__name==bob.

Values must be quoted with single or double quotes when they include special characters or spaces: name=="bob katz".

Comparisons may be combined using logical operators: ; for a logical AND, and , for a logical OR: name=="bob";age>=30. AND has priority over OR; grouping is available using parentheses: name=="bob";(age>=30,age<3).

Note: RQL/RSQL/FIQL support is still incomplete, it will be enhanced over time.

Configuration

RQL_FILTER_QUERY_PARAM sets the querystring parameter name to use; it defaults to 'q'.

Using without rest-framework

You may use the backend manually outside a rest-framework viewset:

from rql_filter.backend import RQLFilterBackend

# May be reused any number of times
backend = RQLFilterBackend()

# Fake request object
class FakeRQLRequest:
    def __init__(self, q):
        self.GET = {'q': q}

qs = Thingy.objects.all()
filtered_qs = backend.filter_queryset(
    FakeRQLRequest('name==bob;age=gt=30'),
    qs,
    None
)

Testing

Install testing dependencies:

pip install -e .[testing]

Run tests:

py.test