Welcome to the Django-modelsearch documentation!

Installation

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

pip install modelsearch

# settings.py

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

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

Configuration

Django Modelsearch indexes into database by default, and it’ll use the built-in full text search features of SQLite, MySQL, MariaDB and PostgreSQL with a fallback for other databases.

To configure an external server like Elasticsearch or OpenSearch, set the MODELSEARCH_BACKENDS setting in your Django settings:

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'modelsearch.backends.elasticsearch9',
        'URLS': ['https://localhost:9200'],
        'INDEX_PREFIX': 'test_',  # Indexes are named {prefix}{app_label}_{model_name}
        'TIMEOUT': 5,
        'OPTIONS': {
            # Options to pass a kwargs to the client
        },
        'INDEX_SETTINGS': {
            # Additional index settings
        },
    }
}

Set the BACKEND for the version of Elasticsearch/OpenSearch you are using:

modelsearch.backends.elasticsearch7 (Elasticsearch 7.x)
modelsearch.backends.elasticsearch8 (Elasticsearch 8.x)
modelsearch.backends.elasticsearch9 (Elasticsearch 9.x)
modelsearch.backends.opensearch2 (OpenSearch 2.x)
modelsearch.backends.opensearch3 (OpenSearch 3.x)

For more details on backend configuration, see Backends.

Indexing

Models need to be indexed before they can be searched. Each searchable model needs to inherit from the modelsearch.index.Indexed class and define a list of search_fields:

from django.db import models
from modelsearch import index

class Person(index.Indexed, models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)

    search_fields = [
        index.SearchField('first_name'),
        index.SearchField('last_name'),
    ]

Once that’s defined, you can then run the rebuild_modelsearch_index management command which will create the index, mappings, and copy all the data.

After initial indexing is complete, Django Modelsearch will use signals to keep the data in sync with your model.

For more information on indexing see Indexing

Searching

Django modelsearch extends the Django ORM to allow QuerySets to be used for search.

To make a model searchable, you need to create a QuerySet that inherits from modelsearch.queryset.SearchableQuerySetMixin and use it on the model’s objects attribute. This will add the .search() method to all QuerySets for the model:

class PersonQuerySet(SearchableQuerySetMixin, QuerySet):
    pass


class Person(index.Indexed, models.Model):
    # ...

    objects = PersonQuerySet.as_manager()

You can now search using Person.objects.search(..).

For more information on searching see Searching.