Django Elasticsearch DSL DRF

0.22.5 verified Fri May 01 auth: no python maintenance

A Django REST framework integration for Elasticsearch DSL. Provides filtering, sorting, searching, faceted search, and more. Current version 0.22.5 (July 2022). Releases are sporadic, with many features stable.

pip install django-elasticsearch-dsl-drf

Common errors

error ImportError: cannot import name 'DocumentViewSet' from 'django_elasticsearch_dsl_drf' ↓

cause Trying to import DocumentViewSet from the top-level package instead of the viewsets submodule.

fix

Use: from django_elasticsearch_dsl_drf.viewsets import DocumentViewSet

error elasticsearch.exceptions.ConnectionError: ConnectionError(('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))) ↓

cause Elasticsearch client version mismatch or server not running.

fix

Ensure Elasticsearch is running and that the installed elasticsearch-py version is compatible (e.g., elasticsearch<7.14 for older library versions).

error ImproperlyConfigured: 'django_elasticsearch_dsl' is not listed in INSTALLED_APPS ↓

cause Missing 'django_elasticsearch_dsl' in INSTALLED_APPS before 'django_elasticsearch_dsl_drf'.

fix

Add both to INSTALLED_APPS: 'django_elasticsearch_dsl', 'django_elasticsearch_dsl_drf'.

Warnings

breaking Version 0.21 dropped support for Python 2.7, 3.5 and Django 1.11, 2.0, 2.1. Upgrading from <0.21 requires Python 3.6+ and Django 2.2+. ↓

fix Ensure your environment uses Python 3.6+ and Django 2.2+.

gotcha The `Elasticsearch` client version must be compatible. The library uses `elasticsearch-dsl` which may require `elasticsearch<7.14` for certain versions. Incompatible client versions cause connection errors. ↓

fix Pin `elasticsearch>=7.0,<7.14` if using older versions of the library, or check compatibility matrix.

deprecated The `FacetedFilterSearchFilterBackend` was added in 0.22.3 but may be unstable; consider using `FilteringFilterBackend` with `faceted` options. ↓

fix Refer to documentation for proper usage; test thoroughly.

gotcha `EmptySearch` may cause `count` to return 0 if not handled (fixed in 0.22.5). If you see incorrect counts, update to 0.22.5 or later. ↓

fix Upgrade to >=0.22.5 or manually handle `EmptySearch` in your backend.

Imports

DocumentViewSet

wrong

from django_elasticsearch_dsl_drf import DocumentViewSet

correct

from django_elasticsearch_dsl_drf.viewsets import DocumentViewSet

Direct import of viewsets from top-level package fails.

BackendFilter

from django_elasticsearch_dsl_drf.filter_backends import FilteringFilterBackend

Quickstart

Basic setup: configure Elasticsearch, define a document, create a DocumentViewSet with filter backends, and register a router.

# settings.py
INSTALLED_APPS = [
    ...
    'django_elasticsearch_dsl',
    'django_elasticsearch_dsl_drf',
]

ELASTICSEARCH_DSL = {
    'default': {
        'hosts': 'localhost:9200'
    },
}

# documents.py
from django_elasticsearch_dsl import Document, Index
from myapp.models import MyModel

PUBLISHED_INDEX = Index('my_models')
PUBLISHED_INDEX.settings(
    number_of_shards=1,
    number_of_replicas=0
)

@PUBLISHED_INDEX.doc_type
def MyModelDocument(Document):
    class Django:
        model = MyModel
        fields = [
            'id',
            'title',
            'description',
        ]

# views.py
from django_elasticsearch_dsl_drf.viewsets import DocumentViewSet
from django_elasticsearch_dsl_drf.filter_backends import (
    FilteringFilterBackend,
    SearchFilterBackend,
    OrderingFilterBackend,
)
from .documents import MyModelDocument
from .serializers import MyModelSerializer

class MyModelDocumentViewSet(DocumentViewSet):
    document = MyModelDocument
    serializer_class = MyModelSerializer
    filter_backends = [
        FilteringFilterBackend,
        SearchFilterBackend,
        OrderingFilterBackend,
    ]
    search_fields = ('title', 'description')
    filter_fields = {
        'title': 'title',
    }
    ordering_fields = {
        'id': 'id',
    }

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import MyModelDocumentViewSet

router = DefaultRouter()
router.register(r'my-models', MyModelDocumentViewSet, basename='mymodel')

urlpatterns = [
    ...
    path('api/', include(router.urls)),
]