Welcome to Django Natural Language Filter’s documentation!¶
The goal of Django NLF is to provide a simple and easy way to express complex filtering criteria. This natural language approach enables building nested complex queries quickly for your users, which are otherwise cumbersome with other libraries.
It provides an intuitive way to start with simpler criteria, but tries not to get in the way of more advanced use cases that need regular expressions, annotations or aggregations etc.
Warning
This project is still in development, please use with this in mind!
Installation¶
Install using pip
,
$ pip install django-nlf
And add django_nlf
to your INSTALLED_APPS
.
INSTALLED_APPS = [
...
"django_nlf",
]
Then you can use the DjangoNLFilter
with a queryset and a string, containing the filter expression. Please see the Language Reference for more details.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | from django_nlf.filters import DjangoNLFilter
from .models import Article
nl_filter = DjangoNLFilter()
qs = Article.objects.all()
q = "author.username is john or title ~ news"
# equivalent to Article.objects.filter(Q(author__username="user") | Q(title__icontains="news"))
articles = nl_filter.filter(qs, q)
# Nested logical operators are also supported:
q = "author.username is john and (title ~ news or created_at <= 2020-06-05)"
# equivalent to
# Article.objects.filter(
# Q(author__username="user") & (Q(title__icontains="news") | Q(created_at__lte="2020-06-05"))
# )
articles = nl_filter.filter(qs, q)
|
Rest framework integration¶
You just need to simply add the natural language filter backend to your filter backends list.
REST_FRAMEWORK = {
"DEFAULT_FILTER_BACKENDS": (
...
"django_nlf.rest_framework.DjangoNLFilterBackend",
),
}