django-elasticsearch-dsl-drf¶
Integrate django-elasticsearch-dsl with Django REST framework in the shortest way possible, with least efforts possible.
Package provides views, serializers, filter backends and other handy tools.
You are expected to use django-elasticsearch-dsl for defining your document models.
Prerequisites¶
- Django 1.8, 1.9, 1.10 and 1.11.
- Python 2.7, 3.4, 3.5, 3.6
- Elasticsearch 2.x, 5.x
Dependencies¶
- django-elasticsearch-dsl
- djangorestframework
Installation¶
Install latest stable version from PyPI:
pip install django-elasticsearch-dsl-drf
or latest stable version from GitHub:
pip install https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/archive/stable.tar.gz
Add
rest_framework
,django_elasticsearch_dsl
anddjango_elasticsearch_dsl_drf
toINSTALLED_APPS
: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.
See it as a guide of diving into integration of Elasticsearch with Django with very low knowledge entry level.
Search¶
Query param name reserved for search is search
. Make sure your models and
documents do not have it as a field or attribute.
Multiple search terms are joined with OR
.
Let’s assume we have a number of Book items with fields title
,
description
and summary
.
Search in all fields¶
Search in all fields (name
, address
, city
, state_province
and
country
) for word “reilly”.
http://127.0.0.1:8080/search/publisher/?search=reilly
Search a single term on specific field¶
In order to search in specific field (name
) for term “reilly”, add
the field name separated with |
to the search term.
http://127.0.0.1:8080/search/publisher/?search=name|reilly
Search for multiple terms¶
In order to search for multiple terms “reilly”, “bloomsbury” add
multiple search
query params.
http://127.0.0.1:8080/search/publisher/?search=reilly&search=bloomsbury
Search for multiple terms in specific fields¶
In order to search for multiple terms “reilly”, “bloomsbury” in specific
fields add multiple search
query params and field names separated with
|
to each of the search terms.
http://127.0.0.1:8080/search/publisher/?search=name|reilly&search=city|london
Filtering¶
Supported lookups¶
Native¶
The following native (to Elasticsearch) filters/lookups are implemented:
term¶
Find documents which contain the exact term specified in the field specified.
http://127.0.0.1:8080/search/books/?tags__term=education&tags__term=economy
range¶
Find documents where the field specified contains values (dates, numbers, or strings) in the range specified.
prefix¶
Find documents where the field specified contains terms which begin with the exact prefix specified.
Functional¶
The following functional (non-native to Elasticsearch, but common in Django) filters/lookups are implemented:
startswith¶
Case-sensitive starts-with.
Testing¶
Project is covered with tests.
To test with all supported Python/Django versions type:
tox
To test against specific environment, type:
tox -e py36-django110
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
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
**************************
Author¶
Artur Barseghyan <artur.barseghyan@gmail.com>
Documentation¶
Contents:
Table of Contents
- django_elasticsearch_dsl_drf package
- Quick start
- Basic Django REST framework integration example
- Advanced Django REST framework integration example
- Various handy helpers