Build Status Coverage Status Code Climate Documentation Status


django-find is a Django app that makes it easy to add complex search/filter functionality for the models in your project. It supports two different ways to search your Django models: Query-based, or JSON-based.

django-find is not a full text search engine, it searches the fields of your models. In other words, it filters on your models and provides tabular data as a result.


Query-based search

By query-based, we mean that you can use statements like these to search your models:

author:"robert frost" and (title:road or chapter:2)

Add a search field to your template using a single tag

{% load find_tags %}
{% find object_list %}
{% for obj in object_list %}
  {{ }}
{% endfor %}

(object_list is a queryset that is passed to the template)

Query in your code

Just add the Searchable mixin:

from django_find import Searchable

class Author(models.Model, Searchable):
    name = models.CharField("Author Name", max_length=10)

And you are good to go:

# Query-based search returns a standard Django QuerySet that you
# can .filter() and work with as usual.
query = Book.by_query('author:"robert frost" and title:"the road"')

# You can also get a Django Q object for the statements.
q_obj = Book.q_from_query('author:"robert frost" and title:"the road"')

Query using JSON

To make it easy to do complex searches spanning multiple models, JSON-based query method is provided. It allows your to make custom searches like these:

Custom Search

For this, a JSON-based search functionality is provided:

    "Book": {"title":[[["notcontains","c"]]]},
    "Chapter": {"content":[[["startswith","The "]]]}

django-find is smart in figuring out how to join those models together and return a useful result. In your code, you can load the JSON and get back the search result:

# JSON-based search exhausts what Django's ORM can do, so it does
# not return a Django QuerySet, but a row-based PaginatedRawQuerySet:
query, field_list = Book.by_json_raw('''{
    "Chapter": {"title":[[["contains","foo"]]]}
for row in query:


Full documentation, including installation instructions, is here: