drf-elasticsearch-dsl

============================= DRF Elasticsearch DSL

.. image:: https://badge.fury.io/py/drf-elasticsearch-dsl.svg :target: https://badge.fury.io/py/drf-elasticsearch-dsl

.. image:: https://circleci.com/gh/ajbeach2/drf-elasticsearch-dsl.svg?style=svg :target: https://circleci.com/gh/ajbeach2/drf-elasticsearch-dsl

.. image:: https://codecov.io/gh/ajbeach2/drf-elasticsearch-dsl/branch/master/graph/badge.svg :target: https://codecov.io/gh/ajbeach2/drf-elasticsearch-dsl

DRF Elasticsearch DSL is losely based on django-haystack_ and provides a ModelSerializerDocument which supports all of the field types provided by elastic-search-dsl persistence_.. ModelSerializerDocument is losely based on the DocType class provided by elasticsearch-dsl.py

The purpose of this libraray is to allow definition of elasticsearch documents with DRF's ModelSerializer_ class while optionally providing support for async document updates and deletes with celery_.

Documentation

The full documentation is at https://drf-elasticsearch-dsl.readthedocs.io.

Quickstart

Install Django Package::

pip install drf-elasticsearch-dsl

Add it to your INSTALLED_APPS:

.. code-block:: python

INSTALLED_APPS = (
    ...
    'drf_elasticsearch_dsl.apps.DrfElasticsearchDsl',
    ...
)

Configure DRF_SERIALIZER_ELASTICSERACH_SETTTINGS in your settings.py file with your elasticsearch url(s)

.. code-block:: python

DRF_SERIALIZER_ELASTICSERACH_SETTTINGS = {
    'elasticsearch_hosts': ['localhost']
}

Create a Model

.. code-block:: python

from django.db import models


class Contact(models.Model):

    first_name = models.CharField(max_length=32, null=False, blank=False)
    last_name = models.CharField(max_length=32, null=False, blank=False)
    url = models.URLField(null=False, blank=False)
    email = models.EmailField(max_length=254, null=False, blank=False)
    bio = models.TextField(null=False, blank=False)
    birthday = models.DateField(null=False, blank=False)

Create a ModelSerializer

.. code-block:: python

from rest_framework import serializers

class ContactSerializer(serializers.ModelSerializer):

    class Meta:
        model = Contact
        fields = '__all__'

Create a search_indexes.py, which should be in the root of the application. Add your ModelSerializerDocument classes here. The specificed index will have its mapping updated for this document.

.. code-block:: python

from drf_elasticsearch_dsl.documents import ModelSerializerDocument
from elasticsearch_dsl import Date, Keyword, Text, String
from .serialziers import ContactSerializer


class ContactSerializerDocument(ModelSerializerDocument):
    first_name = String()
    last_name = String()
    url = Keyword()
    email = Keyword()
    bio = Text()
    birthday = Date()

    class Meta:
        index = 'myapp'
        serializer = ContactSerializer
        doc_type = 'myapp.contact'

Finally, sync your database with elasticsearch by running:

::

$ python manage.py update_index

Features

Celery Support ^^^^^^^^^^^^^^^

By default, dr-elasticsearch-dsl does not setup signals to sync models on save or delete. To enable celery support, add the following to your settings.py confiration:

.. code-block:: python

DRF_SERIALIZER_ELASTICSERACH_SETTTINGS = {
    ...
    'signal_processor_class': 'drf_elasticsearch_dsl.signals.CelerySignalProcessor',
}

See the celery_ documentation for details setting up celery with django

Running Tests

Does the code actually work?

::

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install -r requirements_test.txt
(myenv) $ tox

TODO:

• Add search URLS to be automatically added to all ModelSerializerDocument added to search_indexes.py
• Better documentation
• Better test coverage

Credits

Tools used in rendering this package:

• Cookiecutter_
• cookiecutter-djangopackage_

.. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _cookiecutter-djangopackage: https://github.com/pydanny/cookiecutter-djangopackage .. _django-haystack: https://github.com/django-haystack/django-haystack .. _elastic-search-dsl persistence: http://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html .. _celery: http://docs.celeryproject.org .. _ModelSerializer : http://www.django-rest-framework.org/api-guide/serializers/#modelserializer