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",
  ),
}

Indices and tables