modelsearch 1.2.1

A library for indexing Django models with Elasicsearch, OpenSearch or database and searching them with the Django ORM.

Django ModelSearch

Django ModelSearch allows you to index Django models and search them using the ORM!

It supports PostgreSQL FTS, SQLite FTS5, MySQL FTS, MariaDB FTS, Elasticsearch (7.x, 8.x, and 9.x), and OpenSearch (2.x and 3.x).

Features:

• Index models in Elasticsearch and OpenSearch and query with the Django ORM
• Reuse existing QuerySets for search, works with Django paginators and django-filter
• Also supports PostgreSQL FTS, MySQL FTS, MariaDB FTS and SQLite FTS5
• Autocomplete
• Faceting
• Per-field boosting
• Fuzzy Search
• Phrase search
• Structured queries
• Multi-table inheritance
• Zero-downtime index rebuilding (uses aliases to atomically swap in a new index when its ready)

This has been built into Wagtail CMS since 2014 and extracted into a separate package in March 2025.

Installation

Install with PIP, then add to INSTALLED_APPS in your Django settings:

pip install modelsearch

# settings.py

INSTALLED_APPS = [
    ...
    "modelsearch",
    ...
]

By default, Django ModelSearch will index into the database configured in DATABASES["default"] and use PostgreSQL FTS, MySQL FTS, MariaDB FTS or SQLite FTS, if available.

If you are using PostgreSQL, you must additionally add django.contrib.postgres to your INSTALLED_APPS setting.

You can change the indexing configuration, or add additional backends with the MODELSEARCH_BACKENDS setting. For example, to configure Elasticsearch:

# settings.py

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'modelsearch.backends.elasticsearch8',
        'URLS': ['https://localhost:9200'],
        'INDEX_PREFIX': 'modelsearch_',
        'TIMEOUT': 5,
        'OPTIONS': {},
        'INDEX_SETTINGS': {},
    }
}

Indexing

To index a model, add modelsearch.index.Indexed to the model class and define some search_fields:

from modelsearch import index
from modelsearch.queryset import SearchableQuerySetMixin


# This mixin adds a .search() method to the models QuerySet
class SongQuerySet(SearchableQuerySetMixin, models.QuerySet):
    pass


# Create a model that inherits from Indexed
class Song(index.Indexed, models.Model):
    name = models.TextField()
    lyrics = models.TextField()
    release_date = models.DateField()
    artist = models.ForeignKey(Artist, related_name='songs')

    objects = SongQuerySet.as_manager()

    # Define a list of fields to index
    search_fields = [
        # Index text fields for full-text search
        # Boost the important fields
        index.SearchField('name', boost=2.0),
        index.SearchField('lyrics'),

        # Index fields that for filtering
        # These get inserted into Elasticsearch for fast filtering
        index.FilterField('release_date'),
        index.FilterField('artist'),

        # Pull in content from related models too
        index.RelatedFields('artist', [
           index.SearchField('name'),
        ]),
    ]

Then run the django-admin rebuild_modelsearch_index to create the indexes, mappings and insert the data. Signals are then used to keep the index in sync with the database.

Searching

Search by calling .search() on the QuerySet!

Song.objects.search("Flying Whales")

Searches also work when reversing ForeignKeys:

opeth.songs.search("Harvest")

You can use Django's .filter(), .exclude() and .order_by() with search too:

Song.objects.filter(release_date__year__lt=1971).search("Iron Man")

The filters are rewitten into the Elasticsearch query to make it run fast with a lot of data.