django-elasticsearch-dsl

To index related models (e.g., via ForeignKey), use ObjectField or NestedField.

• ObjectField: Used for standard object relationships.
• NestedField: Used when you need to maintain the relationship between sub-documents in Elasticsearch.

When using these, you should:

1. Define the properties dictionary mapping sub-field names to field instances.
2. Add the related models to the related_models list in the Django inner class to ensure the document is re-indexed when the related object changes.
3. Implement get_instances_from_related(self, related_instance) to tell the library how to find the parent document(s) from the related object.
4. (Optional) Override get_queryset() to use select_related for better performance.

@registry.register_document
class CarDocument(Document):
    manufacturer = fields.ObjectField(properties={
        'name': fields.TextField(),
        'country_code': fields.TextField(),
    })
    ads = fields.NestedField(properties={
        'description': fields.TextField(),
        'title': fields.TextField(),
        'pk': fields.IntegerField(),
    })

    class Django:
        model = Car
        fields = ['name', 'color']
        related_models = [Manufacturer, Ad]

    def get_instances_from_related(self, related_instance):
        if isinstance(related_instance, Manufacturer):
            return related_instance.car_set.all()
        elif isinstance(related_instance, Ad):
            return related_instance.car

To contribute to the project, follow these steps to set up a local development environment:

1. Fork and Clone: Fork the repository on GitHub and clone your fork locally.
2. Virtual Environment: Create a virtual environment and install your local copy in development mode using setup.py develop.
3. Branching: Create a new branch for your specific bugfix or feature.
4. Verification: Before submitting, ensure your changes pass linting with flake8, pass the local test suite, and pass compatibility tests via tox.
5. Submission: Commit your changes, push to your GitHub fork, and submit a pull request.

# 1. Clone your fork
$ git clone git@github.com:your_name_here/django-elasticsearch-dsl.git

# 2. Set up virtualenv and install in development mode
$ mkvirtualenv django-elasticsearch-dsl
$ cd django-elasticsearch-dsl/
$ python setup.py develop

# 3. Create a development branch
$ git checkout -b name-of-your-bugfix-or-feature

# 4. Run linting and tests
$ flake8 django_elasticsearch_dsl tests
$ python setup.py test
$ tox

# 5. Commit and push
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

While using class Index inside a Document class is the standard approach, you can also define an index by instantiating elasticsearch.dsl.Index directly.

To use this method:

1. Instantiate Index with the desired name.
2. Configure settings using .settings().
3. Use the @car.document decorator on your Document class to associate it with that index.
4. Use the @registry.register_document decorator to register the document with django-elasticsearch-dsl.

Alternatively, you can define index settings and names within an inner class Index inside your Document class.

# Method 1: Direct Index instantiation
from elasticsearch.dsl import Index
from django_elasticsearch_dsl import Document, registry
from .models import Car

car_index = Index('cars')
car_index.settings(number_of_shards=1, number_of_replicas=0)

@registry.register_document
@car_index.document
class CarDocument(Document):
    class Django:
        model = Car
        fields = ['name', 'color']

# Method 2: Inner Index class
@registry.register_document
class ManufacturerDocument(Document):
    class Index:
        name = 'manufacture'
        settings = {'number_of_shards': 1, 'number_of_replicas': 0}

    class Django:
        model = Manufacturer
        fields = ['name', 'country_code']

To index a Django model, create a subclass of django_elasticsearch_dsl.Document in a documents.py file within your app directory. Register this class using the @registry.register_document decorator.

Inside the Document class, you define two inner classes:

1. class Index: Defines Elasticsearch-specific settings like the index name and settings (shards, replicas, etc.).
2. class Django: Links the document to a specific Django model and defines which fields to index. It also allows for advanced configuration like signal handling, refresh policies, and queryset pagination.

# documents.py

from django_elasticsearch_dsl import Document
from django_elasticsearch_dsl.registries import registry
from .models import Car

@registry.register_document
class CarDocument(Document):
    class Index:
        name = 'cars'
        settings = {'number_of_shards': 1, 'number_of_replicas': 0}

    class Django:
        model = Car
        fields = ['name', 'color', 'description', 'type']
        # ignore_signals = True
        # auto_refresh = False
        # queryset_pagination = 5000