A filtering and sorting DSL for the Django REST framework
This package provides a small domain-specific language (DSL) for filtering and sorting the views provided using Django REST framework by GET parameters.
The filtering and sorting is performed by Django's querysets, so the SQL injection protection provided by django is also used for the filtering. The fields of the model can be used in the queries in the DSL.
The basic filter syntax for a comparison of a field to a value is as follow
[field] ([negation]) [filter operator] [value]
The field is the name of the model field to be queried. The value is the
value the field shall be compared to. Values for strings and timestamps need
to be quoted in single quotes. For boolean fields the values true and false
are valid.
The possible values for the filter operator are listed in the table futher
below. Some of these filters can be negated with the optional keyword not, to see
which operators support negation also see the table below.
| Filter operator | Alias | Meaning | Negatable with "not" | Field type requirements |
|---|---|---|---|---|
= |
eq |
"equal to" | = is not, but the eq alias is negatable |
- |
!= |
not eq |
"not equal to" | no | - |
< |
lt |
"less than" | no | - |
> |
gt |
"greater than" | no | - |
<= |
lte |
"less than or equal to" | no | - |
>= |
gte |
"greater than or equal to" | no | - |
contains |
substring search (case sensitive) | yes | requires text or char fields | |
icontains |
substring search (case insensitive) | yes | requires text or char fields | |
startswith |
substring search at the beginning of the field value (case sensitive) | yes | requires text or char fields | |
istartswith |
substring search at the beginning of the field value (case insensitive) | yes | requires text or char fields | |
endswith |
substring search at the end of the field value (case sensitive) | yes | requires text or char fields | |
iendswith |
substring search at the end of the field value (case insensitive) | yes | requires text or char fields | |
isnull |
value must be NULL | yes | - |
It is possible to combine multiple filters using the logical operators and
and or. or has precedence over and. It is also possible to use parenthesis: ( and ).
The default name of the GET parameter for filtering is filter.
The basic sorting syntax is
([direction])(field)
The name of the field is mandatory. The direction is optional an when not set
+, which means ascending order is implied. To sort in descending order use
-.
Multiple sorting operations can be chained by separating them with ,. The
first terms will be used first for the ordering, then the following term(s)
will be used.
The default name of the GET parameter for sorting is sort.
The queries in this section use the API provided by the unittest
application in the tests directory of this repository.
The queries need to be correctly escaped before being send. The ones
listed further down this section are listed un-escaped for a better
readability. Escape should happen in the following form: age < legs should be
escaped to become:
GET /animal?filter=age+%3C+legs
| Description | Filter query | Sort query |
|---|---|---|
| An empty filter | ||
| Match an integer field | age = 132 | |
| Match the boolean field "is_bird" to be true | is_bird = true | |
| Match NULL values | favorite_food isnull | |
| Match Non-NULL values | favorite_food not isnull | |
| Compare a timestamp | birthday < '2007-10-13T11:13:09.250219+00:00' | |
| Chain multiple filters with "AND" | name = 'tortoise' and age >= 100 | |
| Chain multiple filters with "OR" | name = 'tortoise' or name = 'dog' | |
| Implicit sort by the field "name" in ascending order | name | |
| Explicit sort by the field "name" in ascending order | +name | |
| Sort by the field "name" in descending order | -name | |
| Sort by the "legs" field in descending order and name in ascending order | -legs,+name | |
| Compare the two fields "age" and "legs" | age < legs | |
| Match the field name to contain the substring "rtoi" | name contains 'rtoi' | |
| Match the field name to NOT contain the substring "rtoi" | name not contains 'rtoi' | |
| Combination of filtering and sorting | name startswith 'd' | sort=-id |
This module just provides a custom DjangoFilterBackend which
can be used like in the following example:
from rest_framework import generics
from rest_framework_filterdsl import FilterDSLBackend
...
class MyListView(generics.ListAPIView):
...
filter_backends = (FilterDSLBackend,)
...
Settings like the names of the GET parameters or the casts for the user-provided
values can be customized by subclassing the FilterDSLBackend implementation.
For more example usage please also see the unittests of this repository. Additional the REST framework filtering documentation may be helpful.
This projects includes a set of unittests implemented using
pytest. To run these use the
runtests.sh script.
See LICENSE.txt.