============================ 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. .. image:: https://img.shields.io/pypi/v/django-elasticsearch-dsl-drf.svg :target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf :alt: PyPI Version .. image:: https://img.shields.io/pypi/pyversions/django-elasticsearch-dsl-drf.svg :target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf/ :alt: Supported Python versions .. image:: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/workflows/test/badge.svg :target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/actions :alt: Build Status .. image:: https://readthedocs.org/projects/django-elasticsearch-dsl-drf/badge/?version=latest :target: http://django-elasticsearch-dsl-drf.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: https://img.shields.io/badge/license-GPL--2.0--only%20OR%20LGPL--2.1--or--later-blue.svg :target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/#License :alt: GPL-2.0-only OR LGPL-2.1-or-later .. image:: https://coveralls.io/repos/github/barseghyanartur/django-elasticsearch-dsl-drf/badge.svg?branch=master :target: https://coveralls.io/github/barseghyanartur/django-elasticsearch-dsl-drf?branch=master :alt: 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 ============================ - :doc:`Dynamic serializer for Documents `. - :doc:`Search filter backend `. - :doc:`Ordering filter backend `. - :doc:`Filtering filter backend ` (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. - :doc:`Geo-spatial filtering filter backend ` (the following filters implemented: ``geo_distance``, ``geo_polygon`` and ``geo_bounding_box``). - :doc:`Geo-spatial ordering filter backend ` (the following filters implemented: ``geo_distance``). - :doc:`Faceted search filter backend `. - :doc:`Post-filter filter backend `. - :doc:`Nested filtering filter backend `. - :doc:`Highlight backend `. - :doc:`Suggester filter backend `. - :doc:`Functional suggester filter backend `. - :doc:`Pagination (Page number and limit/offset pagination) `. - :doc:`Ids filter backend `. - :doc:`Multi match search filter backend `. - :doc:`Simple search query search filter backend `. - :doc:`More-like-this support (detail action) `. - :doc:`Global aggregations support `. - :doc:`Source filter backend `. 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`. .. code-block:: sh docker-compose up It will set up: - Elasticsearch on `http://localhost:9200 `_ - Django REST framework on `http://localhost:8000 `_ - React on `http://localhost:3000 `_ Installation ============ (1) Install latest stable version from PyPI: .. code-block:: sh pip install django-elasticsearch-dsl-drf or latest stable version from GitHub: .. code-block:: 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``: .. code-block:: 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 :doc:`quick start tutorial `. 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: .. code-block:: sh tox To test against specific environment, type: .. code-block:: sh tox -e py38-django30 To test just your working environment type: .. code-block:: sh ./runtests.py To run a single test in your working environment type: .. code-block:: sh ./runtests.py src/django_elasticsearch_dsl_drf/tests/test_filtering.py Or: .. code-block:: sh ./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: .. code-block:: sh ./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: .. code-block:: sh pip install -r examples/requirements/test.txt Writing documentation ===================== Keep the following hierarchy. .. code-block:: text ===== 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