Need help with django-elasticsearch?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

207 Stars 70 Forks MIT License 145 Commits 33 Opened issues


Simple wrapper around elasticsearch-py to index/search a django Model.

Services available


Need anything else?

Contributors list

django_elasticsearch is a wrapper around py-elasticsearch that automates the indexation and search of django models.
Note: if your elasticsearch documents/mappings are not close to django models, this package is probably not for you.


  • Install and launch elasticsearch if it's not done already.

  • Install py-elasticsearch

    pip install elasticsearch
  • Install djangoelasticsearch ```shell pip install git+ ``` Note: no pypy package yet


As stated in the python elasticsearch module documentation:

There are two branches for development - master and 0.4. Master branch is used to track all the changes for Elasticsearch 1.0 and beyond whereas 0.4 tracks Elasticsearch 0.90.

Releases with major version 1 (1.X.Y) are to be used with Elasticsearch 1.* and later, 0.4 releases are meant to work with Elasticsearch 0.90.*.

django_elasticsearch has only been tested with Elasticsearch 1.3.9 and it's corresponding python interface version 1.2.0, but since the API hasn't change i'm quite positive that newer and older versions should work fine too, as long as you use the right python module for your Elasticsearch version. See the official docs on the matter.


Subclass the models you wish to index/search with

. ```python from django.db import models from django_elasticsearch.models import EsIndexable

MyModel(EsIndexable, models.Model): foo = models.CharField(max_length=64) [...]

Then you can do:
>>> q ='value')
>>> q
[{'id': 1, 'foo': 'A value'}, {'id': 2, 'foo': 'Another value'}, ...]
>>> q.deserialize()
[, , ...]
{'id': 1, 'foo': 'A value'}

The elasticsearch manager methods (all, search, mlt) returns an instance of a EsQueryset, it's like a django Queryset but it queries elasticsearch instead of your db.
Like a regular Queryset, an EsQueryset is lazy, and if evaluated, returns a list of documents. The

method makes the queryset return instances of models instead of dicts.

django-elasticsearch DOES NOT index documents by itself unless told to, either set settings.ELASTICSEARCHAUTOINDEX to True to index your models when you save them, or call directly

To specify the size of output of documents, it is necessary to make a slice of data, for example:

>>> 10
>>> 42


Project scope configuration (django settings):

    Defaults to 'http://localhost:9200'
    The url of your elasticsearch cluster/instance.

    Defaults to False
    Set to True if you don't want to handle the elasticsearch operations yourself. In that case the creation of the index, the indexation and deletions are hooked respectively to the postsyncdb, postsave and postdelete signals. Should probably only be used in a dev environment or for small scale databases. If you have already done a syncdb, you can just call `````` to create the index/mapping.

    Defaults to 'django'
    The default index name used for every document, can be overrided for a model with the

    No defaults
    If set, will be passed when creating any index as is.

    Defaults to 0.5
    Will be applied to any query, See the fuzziness section of the elasticsearch documentation.

    Defaults to {}
    Additional kwargs to be passed to at the instantiation of the elasticsearch client. Useful to manage HTTPS connection for example (Reference).

Model scope configuration:

Each EsIndexable model receive an Elasticsearch class that contains its options (just like the Model.Meta class).

  • index
    Defaults to 'django'
    The elasticsearch index in which this model(document type) will be indexed.

  • doc_type
    Defaults to 'model-{model_name}'
    The elasticsearch type in which this model will be indexed.

  • fields
    Defaults to None
    The fields to be indexed by elasticsearch, if left to None, all models fields will be indexed.

  • mappings
    Defaults to None
    You can override some or all of the fields mapping with this dictionary Example:

    MyModel(EsIndexable, models.Model):
        title = models.CharField(max_length=64)
    class Elasticsearch(EsIndexable.Elasticsearch):
        mappings = {'title': {'boost': 2.0}}

    In this example we only override the 'boost' attribute of the 'title' field, but there are plenty of possible configurations, see the docs.

  • serializer_class
    Defaults to EsJsonSerializer
    This is the class used to translate from the django model to elasticsearch document both ways.

  • facets_fields
    Defaults to None
    Can be set to a list of fields to return as facets when doing a search query on the model, if not set explicitly in the query itself.

  • facets_limits
    Defaults to None
    The maximum number of facets to return per query, if None, use the elasticsearch setting.

  • suggest_fields
    Defaults to None
    A dictionary of fields to add in the suggestions, if not set at a search level.

  • suggest_limit
    Defaults to None
    The maximum number of suggestions to return, if None, use the elasticsearch setting.

  • completion_fields
    Defaults to None
    The fields on which to activate auto-completion (needs a specific mapping).


EsIndexable API:

The Elasticsearch manager is available from the 'es' attribute of EsIndexable Model classes or instances. Some methods requires an instance though.

Manager methods that returns a EsQueryset instance

  •, facets=None, facetslimit=None, globalfacets=True, suggestfields=None, suggestlimit=None, fuzziness=None)
    Returns a configured EsQueryset with the given options, or the defaults set in

  • es.all()
    Proxy to an empty query

  • es.mlt needs_instance
    Returns an EsQueryset of documents that are 'like' the given instance's document. See the more like this api.

Other Manager methods
* es.count()
Returns the number of documents in the model's doc_type.

  • es.get() needs_instance
    Returns the elasticsearch document of the model instance.

  • es.delete() needs_instance
    Delete the given instance's document.

  • es.do_index() needs_instance
    Serialize and index the given instance.

  • es.complete(fieldname, query)
    Returns a list of suggestions from elasticsearch for the given field and query. Note: field
    name must be present in

    because it needs a specific mapping. Example: ```'title', 'tset') ['test',] ```

  • es.do_update()
    Refresh the whole index of the model. This should probably be only used in a TestCase. See the refresh api.

  • es.get_mapping()
    Returns the current mapping for the model's document type.

  • es.get_settings()
    Returns the current settings for the model's index.

  • es.diff()
    Returns a dict containing differences between the db instance and the elasticsearch instance.

  • es.check_cluster()
    Returns True if the elasticsearch cluster is alive.

  • es.reindex_all(queryset=None)
    queryset defaults to


    for every instance in queryset.
  • es.flush()
    Deletes the model's index and then reindex all instances of it.

EsQueryset API:

This class is as close as possible to a standard relational db Queryset, however the db operations (update and delete) are deactivated (i'm open for discussion on if and how to implement these). Note that just like regular Querysets, EsQuerysets are lazy, they can be ordered, filtered and faceted.

Note that the return value of the queryset is higly dependent on your mapping, for example, if you want to be able to do an exact filtering with filter() you need a field with {"index" : "notanalyzed"}. Also by default, filters are case insensitive, if you have a case sensitive tokenizer, you need to instantiate EsQueryset with ignorecase=False.

An EsQueryset acts a lot like a regular Queryset: ```

q = q = q.filter(title='foo') q ='test') q # only now is the query evaluated [{'title': 'foo', 'some_content': 'this is a test.'}] ```

If you need models methods or attributes, you can get model instances instead of documents (dicts) by calling the deserialize method on the query before evaluating it. See the Serializer API below.

To access the facets you can use the facets property of the EsQueryset: ```python

MyModel.Elasticsearch.defaultfacetsfields ['author'] q ='woot', facets=['foo']) # returns a lazy EsQueryset instance q ='woot').facet(['foo']) # is exactly the same q.facets # evals the query and returns the facets {u'doccount': 45, u'foo': {u'buckets': [ {u'doccount': 13, u'key': u'bar'}, ]}}

Note that automatically add the default facets set on the model to the query, but you can also set them manually with the
facets_limit``` parameters.

Available methods all of those are chainable. *

  • es.queryset.all()

  • es.queryset.facet(fields, limit=None, useglobals=True)
    If ```use
    globals``` is set to False, the facets will be filtered like the documents.

  • es.queryset.suggest(fields, limit)

    for suggestions.
  • es.queryset.order_by(**kwargs)

  • es.queryset.filter(**kwargs)
    Accepted lookups are: _exact, _should, _contains, _gt, _gte, _lt, _lte, _range
    Just like in django, the default lookup is _exact.
    See the bool query for a difference between _
    exact (which maps to 'must') and __should.

  • es.queryset.exclude(**kwargs)

  • es.queryset.mlt(id)
    See the more like this api.

  • es.queryset.deserialize() Makes the queryset return model instances instead of documents.

  • es.queryset.extra(body) Blindly updates the elasticsearch query body with

    allowing to use any non-implemented elasticsearch feature.

Does not return an EsQueryset and thus are not chainable.
* es.queryset.count()

  • es.queryset.get(pk=X)

  • es.queryset.complete(field_name, query)

Serializer API:

The serializer's role is to format django model instances to something indexable by elasticsearch : json. The only mandatory method for a serializer is the

method, deserializing is only an option.

The default serializer does a little bit more though:
For each indexed fields, look for either

methods, and fallback on
getattr(instance, field_name)
. Also allow naive nested serialization, by looking for an Elasticsearch class attribute on the target model class of the related field, or falling back on
dict(, value=unicode(instance))
Let's look at a bit complex example:
```python from django.db import models from django
elasticsearch.models import EsIndexable from my_app.serializers import MyModelEsSerializer

class MyModel(models.Model): somecontent = models.CharField(maxlength=255) morecontent = models.TextField() adate = models.DateTimeField(autonowadd=True) anotherdate = models.DateTimeField(autonow=True) some_relation = models.ForeignKey(AnotherModel)

  class Elasticsearch(EsIndexable.Elasticsearch):
        serializer_class = MyModelEsSerializer
        fields = ['some_content', 'more_content', 'content_length', 'a_date', 'some_relation']
        mappings = {'content_length': {'type': 'long'},
                    'a_date': {'type': 'object'}}
Note that since ```content_length``` is an abstract field (not present in db), and ```a_date``` is serialized to a dict instead of it's default (datetime), we need to tell elasticsearch their types in the mappings attribute.

```python from django_elasticsearch.serializers import EsJsonSerializer

class MyModelEsSerializer(EsJsonSerializer): def serialize_more_content(self, instance, field_name): # Specific attribute serializer return getattr(instance, field_name)[:5]

def serialize_content_length(self, instance, field_name):
    # Abstract field serializer
    content = getattr(instance, 'some_content')
    return len(content)

def serialize_type_datetimefield(self, instance, field_name):
    # Specific field type serializer
    d = getattr(instance, field_name)
    # A rather typical api output,
    # The reasons for indexing dates as this are debatable, but it's just an example
    return {
        'timestamp': d and d.strftime('%s'),
        'date': d and,
        'time': d and d.time().isoformat()[:5]

output ```python

instance = MyModel(somecontent=u"This is some minimalist content.", morecontent=u"And that too.") "{'somecontent': 'This is some minimalist content.', 'morecontent': 'And t', 'contentlength': 32, 'adate': { 'timestamp': '1434452101', 'date': '2015-06-16', 'time': '05:53:56.626532' }, 'some_relation': {'id': 15, 'value': 'something something'} }" ```


  • restframework.ElasticsearchFilterBackend
    A filter backend for rest framework that returns a EsQueryset.

  • restframework.FacetedListModelMixin
    A viewset mixin that adds the facets to the response data in case the ElasticsearchFilterBackend was used.


Two loggers are available 'elasticsearch' and 'elasticsearch.trace'.


You can catch

if you want to recover from an error on elasticsearch side. There is an example of it in
. You can also use the
method which returns True if the cluster is available, in case you want to make sure of it before doing anything.


Django-elasticsearch has a 95% test coverage, and tests pass for django 1.4 to 1.9.

Using tox

Install tox, then:

cd test_project

Or to test one specific python/django version combo:

tox -e py27-django16

Or a specific test case / unit test, with a weird syntax: Django 1.4

tox -epy27-django14 -- .EsQuerysetTestCase
tox -epy27-django14 -- .EsQuerysetTestCase.test_use_cache

Django >1.6

tox -epy27-django16 -- .tests.test_qs.EsQuerysetTestCase
tox -epy27-django16 -- .tests.test_qs.EsQuerysetTestCase.test_use_cache

The old way

$ cd test_project
$ virtualenv env
$ . env/bin/activate
$ pip install -r ../requirements.txt  # app requirements
$ pip install -r requirements.txt  # tests requirements
$ python test django_elasticsearch


coverage run --source=django_elasticsearch --omit='*tests*','*migrations*' test django_elasticsearch


Why not make a django database backend ? Because django does not support non relational databases, which means that the db backend API is very heavily designed around SQL. I'm usually in favor of hiding the complexity, but in this case for every bit that feels right - auto db and test db creation, client handling, .. - there is one that feels wrong and keeping up with the api changes makes it worse. There is an avorted prototype branch (feature/db-backend) going this way though.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.