django-opensearch-models

Index your Django models in OpenSearch and keep them in sync automatically.

You describe an index by declaring a Document class against a model, and the library handles the rest: it builds the OpenSearch mapping from your Django fields, populates the index, and updates it on every save() and delete() through Django's signal framework. Search results convert back into real Django querysets when you need them.

What you get

• Declarative documents. A Document subclass maps a Django model to an OpenSearch index — fields, analyzers, index settings and all.
• Automatic synchronisation. Model changes reach the index through signals, either inline or handed to Celery as background tasks.
• Related-model tracking. Declare related_models and edits to a ForeignKey target re-index the documents that embed it.
• Management commands. Create, populate, rebuild and delete indices, with zero-downtime rebuilds behind an alias and optional parallel indexing.
• Querysets from search results. .to_queryset() turns a search response back into a Django queryset, ordered to match the search.

Requirements

Every combination in that table is exercised nightly against a real OpenSearch cluster, under both signal processors.

Installation

$ pip install django-opensearch-models

Quick start

Add the app and point it at your cluster:

# settings.py

INSTALLED_APPS = [
    ...,
    "django_opensearch_models",
]

OPENSEARCH = {
    "default": {
        "hosts": "localhost:9200",
        "http_auth": ("username", "password"),
    },
}

Declare a document for the model you want to index, in your app's documents.py:

# documents.py

from django_opensearch_models import Document
from django_opensearch_models.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"]

Build the index:

$ ./manage.py search_index --rebuild

From here on, saving a Car indexes it. Searching returns OpenSearch hits, or Django objects:

hits = CarDocument.search().filter("term", color="red")

for hit in hits:
    print(hit.name, hit.description)

# ...or come back to the ORM
cars = CarDocument.search().filter("term", color="red")[:30].to_queryset()

Documentation

Full documentation is at django-opensearch-models.readthedocs.io.

• Quickstart — install, configure, index and search
• Indices — index objects, aliases and the post_index signal
• Fields — field types, relationships and custom mappings
• Settings — every setting the app reads
• Commands — the search_index management command
• Contributing — running the tests and the support matrix

Contributing

Issues and pull requests are welcome at github.com/django-opensearch/django-opensearch-models. See the contributing guide for how to run the test suite against a throwaway OpenSearch container.

License

Apache-2.0. See LICENSE and NOTICE.