barseghyanartur/django-elasticsearch-dsl-drf

Integrate Elasticsearch DSL with Django REST framework.

django
django-rest-framework
django-rest-framework-addon
djangorestframework
elasticsearch
elasticsearch-dsl

django-elasticsearch-dsl-drf

Integrate Elasticsearch DSL with Django REST framework in the shortest way possible, with least efforts possible.

Package provides views, serializers, filter backends, pagination and other handy add-ons.

You are expected to use django-elasticsearch-dsl for defining your Elasticsearch documents.

PyPI Version

Supported Python versions

Build Status

Documentation Status

GPL-2.0-only OR LGPL-2.1-or-later

Coverage

Documentation

Documentation is available on Read the Docs.

Make sure to read FAQ.

Prerequisites

  • Django 2.2, 3.1 and 3.2.
  • Python 3.6, 3.7, 3.8 and 3.9.
  • Elasticsearch 6.x, 7.x. For older versions use django-elasticsearch-dsl-drf version 0.18.

Main features and highlights

  • Dynamic serializer for Documents <basic_usage_examples>{.interpreted-text role="doc"}.
  • Search filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Ordering filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Filtering filter backend <advanced_usage_examples>{.interpreted-text role="doc"} (big variety of native- and functional- query lookups, such as gt, gte, lt, lte, endswith, contains, wildcard, exists, exclude, isnull, range, in, prefix (same as startswith), term and terms is implemented.
  • Geo-spatial filtering filter backend <advanced_usage_examples>{.interpreted-text role="doc"} (the following filters implemented: geo_distance, geo_polygon and geo_bounding_box).
  • Geo-spatial ordering filter backend <advanced_usage_examples>{.interpreted-text role="doc"} (the following filters implemented: geo_distance).
  • Faceted search filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Post-filter filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Nested filtering filter backend <nested_fields_usage_examples>{.interpreted-text role="doc"}.
  • Highlight backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Suggester filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Functional suggester filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Pagination (Page number and limit/offset pagination) <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Ids filter backend <advanced_usage_examples>{.interpreted-text role="doc"}.
  • Multi match search filter backend <search_backends>{.interpreted-text role="doc"}.
  • Simple search query search filter backend <search_backends>{.interpreted-text role="doc"}.
  • More-like-this support (detail action) <more_like_this>{.interpreted-text role="doc"}.
  • Global aggregations support <global_aggregations>{.interpreted-text role="doc"}.
  • Source filter backend <source_backend>{.interpreted-text role="doc"}.

Do you need a similar tool for GraphQL? Check graphene-elastic.

Demos

Online demo

Check the live demo app (Django 3.1 + Django REST Framework 3.12 + Elasticsearch 7.5) hosted on Heroku and bonsai.io.

Local demo

A frontend demo (React based) is available. See the dedicated docs for more information.

To bootstrap evaluation, clone the repository locally and run [docker-compose]{.title-ref}.

docker-compose up

It will set up:

Installation

(1) Install latest stable version from PyPI:

``` sh
pip install django-elasticsearch-dsl-drf
```

or latest stable version from GitHub:

``` sh
pip install https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/archive/stable.tar.gz
```

(2) Add rest_framework, django_elasticsearch_dsl and django_elasticsearch_dsl_drf to INSTALLED_APPS:

``` python
INSTALLED_APPS = (
    # ...
    # REST framework
    'rest_framework',

    # Django Elasticsearch integration
    'django_elasticsearch_dsl',

    # Django REST framework Elasticsearch integration (this package)
    'django_elasticsearch_dsl_drf',
    # ...
)
```

Quick start

Perhaps the easiest way to get acquainted with django-elasticsearch-dsl-drf is to read the quick start tutorial <quick_start>.

See it as a guide of diving into integration of Elasticsearch with Django with very low knowledge entry level.

Testing

Project is covered with tests.

To test with all supported Python/Django versions type:

tox

To test against specific environment, type:

tox -e py38-django30

To test just your working environment type:

./runtests.py

To run a single test in your working environment type:

./runtests.py src/django_elasticsearch_dsl_drf/tests/test_filtering.py

Or:

./manage.py test django_elasticsearch_dsl_drf.tests.test_ordering

To run a single test class in a given test module in your working environment type:

./runtests.py src/django_elasticsearch_dsl_drf/tests/test_suggesters.py::TestSuggesters

It\'s assumed that you have all the requirements installed. If not, first install the test requirements:

pip install -r examples/requirements/test.txt

Writing documentation

Keep the following hierarchy.

=====
title
=====

header
======

sub-header
----------

sub-sub-header
~~~~~~~~~~~~~~

sub-sub-sub-header
^^^^^^^^^^^^^^^^^^

sub-sub-sub-sub-header
++++++++++++++++++++++

sub-sub-sub-sub-sub-header
**************************

License

GPL-2.0-only OR LGPL-2.1-or-later

Support

For any issues contact me at the e-mail given in the Author section.

Author

Artur Barseghyan \<artur.barseghyan@gmail.com>

Stars
365
-0.27% more than last month
Forks
116
Open Issues
62