Django Elasticsearch DSL

9.0 · active · verified Wed Apr 15

django-elasticsearch-dsl is a Django application that wraps elasticsearch-dsl-py to provide an easy way to integrate Elasticsearch with Django models. It simplifies document definition, index management, and provides signal processors for automatic indexing of model changes. The current version is 9.0, and the project maintains an active release cadence with regular updates and support for new Django and Elasticsearch versions.

Warnings

breaking Version 8.0 dropped support for Python 2.7, 3.6, 3.7. It now requires Python >=3.9. It also dropped support for Django versions 1.11, 2.x, 3.x, and 4.0, now requiring Django >=4.1. This release also introduces support for Elasticsearch 8.
Fix: Upgrade your Python environment to >=3.9 and Django to >=4.1 before upgrading django-elasticsearch-dsl to 8.0+. If using Elasticsearch, ensure compatibility with Elasticsearch 8.
breaking The major version bump from 6.x to 7.x aligned with elasticsearch-dsl-py's move from `DocType` to `Document` (and dropping compatibility with older Elasticsearch server versions, notably <6.x). This requires updating document definitions if migrating from a very old version.
Fix: Review your `DocType` definitions and convert them to `Document` subclasses. Ensure your Elasticsearch server is version 6.x or newer (and 7.x is recommended for `django-elasticsearch-dsl` 7.x).
gotcha Incorrect or missing Elasticsearch connection settings in `settings.py` (ELASTICSEARCH_DSL) is a common issue. If connections are not properly defined, operations will fail silently or with connection errors.
Fix: Always ensure your `ELASTICSEARCH_DSL` dictionary in `settings.py` is correctly configured with at least a 'default' host. Use environment variables for sensitive data like hostnames or credentials.
gotcha For real-time indexing of Django model changes (create, update, delete), you must configure a signal processor, e.g., `ELASTICSEARCH_DSL_SIGNAL_PROCESSOR = 'django_elasticsearch_dsl.signals.RealTimeSignalProcessor'`. Without it, your Elasticsearch index will become stale.
Fix: Add `ELASTICSEARCH_DSL_SIGNAL_PROCESSOR` to your `settings.py` and choose an appropriate signal processor. For production, consider using an asynchronous processor like CelerySignalProcessor for better performance.

Install

pip install django-elasticsearch-dsl Install stable version

Imports

Document

from django_elasticsearch_dsl import Document

Index

from django_elasticsearch_dsl import Index

registry

from django_elasticsearch_dsl.registries import registry

fields
```
from elasticsearch_dsl import fields
```
Document fields are imported directly from elasticsearch-dsl, not django-elasticsearch-dsl.

Quickstart

To get started, define your Elasticsearch settings in `settings.py`. Create a `Document` subclass for your Django model, register it with the `registry`, and define its fields using `elasticsearch_dsl.fields`. You can then rebuild your Elasticsearch index using the `search_index` management command and perform searches through the `Document`'s `.search()` method. Remember to configure a signal processor for real-time indexing.

import os

# models.py (example_app)
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    published = models.BooleanField(default=False)

    def __str__(self):
        return self.title

# documents.py (example_app)
from django_elasticsearch_dsl import Document, Index
from django_elasticsearch_dsl.registries import registry
from elasticsearch_dsl import fields

from .models import Article

# Define a custom index
article_index = Index('articles')
article_index.settings(number_of_shards=1, number_of_replicas=0)

@registry.register_document
@article_index.document
class ArticleDocument(Document):
    id = fields.IntegerField(attr='id')
    title = fields.TextField(
        analyzer='english',
        fields={'raw': fields.KeywordField()}
    )
    body = fields.TextField(
        analyzer='english',
        fields={'raw': fields.KeywordField()}
    )
    published = fields.BooleanField()

    class Django:
        model = Article
        fields = ['title', 'body', 'published']

# In settings.py:
# ELASTICSEARCH_DSL = {
#     'default': {
#         'hosts': os.environ.get('ES_HOST', 'localhost:9200'),
#         'timeout': 60
#     }
# }
# ELASTICSEARCH_DSL_SIGNAL_PROCESSOR = 'django_elasticsearch_dsl.signals.RealTimeSignalProcessor'

# To rebuild index:
# python manage.py search_index --rebuild

# Example search query:
# from example_app.documents import ArticleDocument
# s = ArticleDocument.search().query('match', title='test article')
# response = s.execute()
# for hit in response:
#     print(hit.title)

view raw JSON →