Haystack for Django REST Framework



Small library aiming to simplify using Haystack with Django REST Framework


Supported Python and Django versions:


It’s in the cheese shop!

$ pip install drf-haystack


  • A Supported Django install
  • Django REST Framework v3.2.0 and later
  • Haystack v2.5 and later
  • A supported search engine such as Solr, Elasticsearch, Whoosh, etc.
  • Python bindings for the chosen backend (see below).
  • (geopy and libgeos if you want to use geo spatial filtering)

Python bindings

You will also need to install python bindings for the search engine you’ll use.


See haystack Elasticsearch docs for details

$ pip install elasticsearch<2.0.0           # For Elasticsearch 1.x
$ pip install elasticsearch>=2.0.0,<3.0.0   # For Elasticsearch 2.x


See haystack Solr docs for details.

$ pip install pysolr


See haystack Whoosh docs for details.

$ pip install whoosh


See haystack Xapian docs for details.


This library has mainly been written by me while working at Inonit. I have also had some help from these amazing people! Thanks guys!



Release date: 2019-10-13

  • Fixed #139. Overriding declared fields must now use serializers.SerializerMethodField() and are handled by stock DRF. We don’t need any custom functionality for this.
  • Added support for Django REST Framework v3.10.x
  • Dropped Python 2.x support


Release date: 2019-05-21

  • Django2.2 support
  • Django REST Framework 3.9.x support


Release date: 2018-08-15

  • Fixed Django2.1 support
  • Replaced requirements.txt with Pipfile for development dependencies management


Release date: 2018-06-16

  • Fixed issues with __in=[...] and __range=[...] filters. Closes #128.


Release date: 2018-05-22

  • Fixed issue with _get_count for DRF v3.8


Release date: 2018-04-20

  • Fixed errors in test suite which caused all tests to run on Elasticsearch 1.x


Release date: 2018-04-16

This release was pulled because of critical errors in the test suite.

  • Dropped support for Django v1.10.x and added support for Django v2.0.x
  • Updated minimum Django REST Framework requirement to v3.7
  • Updated minimum Haystack requirements to v2.8


Release date: 2018-01-30

  • Fixes issues with building documentation.
  • Fixed some minor typos in documentation.
  • Dropped unittest2 in favor of standard lib unittest


Release date: 2018-01-06

  • Locked Django versions in order to comply with Haystack requirements.
  • Requires development release of Haystack (v2.7.1dev0).


Release date: 2018-01-06 (Removed from pypi due to critical bugs)

  • Bumping minimum support for Django to v1.10.
  • Bumping minimum support for Django REST Framework to v1.6.0
  • Adding support for Elasticsearch 2.x Haystack backend


Release date: 2017-01-13

  • Updated docs with correct name for libgeos-c1.
  • Updated .travis.yml with correct name for libgeos-c1.
  • Fixed an issue where queryset in the whould be evaluated if attribute is set but has no results, thus triggering the wrong clause in condition check. PR#88 closes #86.


Release date: 2016-11-08

  • Added Django 1.10 compatibility.
  • Fixed multiple minor issues.


Release date: 2016-06-29

  • Fixed #61. Introduction of custom serializers for serializing faceted objects contained a breaking change.


Release date: 2016-06-28

  • Restructured and updated documentation
  • Added support for using a custom serializer when serializing faceted objects.


Release date: 2016-06-24


This release include breaking changes to the API

  • Dropped support for Python 2.6, Django 1.5, 1.6 and 1.7
  • Will follow Haystack’s supported versions
  • Removed deprecated SQHighlighterMixin.
  • Removed redundant BaseHaystackGEOSpatialFilter. If name of indexes.LocationField needs to be changed, subclass the HaystackGEOSpatialFilter directly.
  • Reworked filters:
    • More consistent naming of methods.
    • All filters follow the same logic for building and applying filters and exclusions.
    • All filter classes use a QueryBuilder class for working out validation and building queries which are to be passed to the SearchQuerySet.
    • Most filters does not inherit from HaystackFilter anymore (except HaystackAutocompleteFilter and HaystackHighlightFilter) and will no longer do basic field filtering. Filters should be properly placed in the filter_backends class attribute in their respective order to be applied. This solves issues where inherited filters responds to query parameters they should ignore.
  • HaystackFacetSerializer narrow_url now returns an absolute url.
  • HaystackFacetSerializer now properly serializes MultiValueField and FacetMultiValueField items as a JSON Array.
  • HaystackGenericAPIView.get_object() optional model query parameter now requires a app_label.model instead of just the model.
  • Extracted internal fields and serializer from the HaystackFacetSerializer in order to ease customization.
  • HaystackFacetSerializer now supports all three builtin pagination classes, and a hook to support custom pagination classes.
  • Extracted the more-like-this detail route and facets list route from the generic HaystackViewSet.


Release date: 2015-12-02

  • Fixed a bug where ignore_fields on HaystackSerializer did not work unless exclude evaluates to True.
  • Removed elasticsearch from install_requires. Elasticsearch should not be a mandatory requirement, since it’s useless if not using Elasticsearch as backend.


Release date: 2015-10-31

  • Added support for Django REST Framework 3.3.0 (Only for Python 2.7/Django 1.7 and above)
  • Locked elasticsearch < 2.0.0 (See #29)


Release date: 2015-10-08

  • Added support for serializing faceted results. Closing #27.


Release date: 2015-10-05


Release date: 2015-08-23

  • Proper support for Multiple search indexes (Github #22).
  • Experimental support for Term Boost (This seems to have some issues upstreams, so unfortunately it does not really work as expected).
  • Support for negate in filters.


Release date: 2015-07-28

  • Support for More Like This results (Github #10).
  • Deprecated SQHighlighterMixin in favor of HaystackHighlightFilter.
  • HaystackGenericAPIView now returns 404 for detail views if more than one entry is found (Github #19).


Release date: 2015-06-29

  • Added support for field lookups in queries, such as field__contains=foobar. Check out Haystack docs for details.
  • Added default permission_classes on HaystackGenericAPIView in order to avoid crash when using global permission classes on REST Framework. See Permissions for details.


Release date: 2015-06-15

  • Fixed issues for Geo spatial filtering on django-haystack v2.4.x with Elasticsearch.
  • A serializer class now accepts a list or tuple of ignore_field to bypass serialization.
  • Added support for Highlighting.


Release date: 2015-05-19

  • HaystackGenericAPIView().get_object() now returns Http404 instead of an empty SearchQueryset if no object is found. This mimics the behaviour from GenericAPIView().get_object().
  • Removed hard dependencies for geopy and libgeos (See Github #5). This means that if you want to use the HaystackGEOSpatialFilter, you have to install these libraries manually.


Release date: 2015-03-23

  • Fixed MissingDependency error when using another search backend than Elasticsearch.
  • Fixed converting distance to D object before filtering in HaystackGEOSpatialFilter.
  • Added Python 3 classifier.


Release date: 2015-02-16

  • Full coverage (almost) test suite
  • Documentation
  • Beta release Development classifier


Release date: 2015-02-14

  • Initial release.

Indices and tables