Backends

Django Modelsearch has support for multiple backends, giving you the choice between using the database for search or an external service such as Elasticsearch.

You can configure which backend to use with the MODELSEARCH_BACKENDS setting:

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'modelsearch.backends.database',
    }
}

`AUTO_UPDATE`

By default, Django Modelsearch will automatically keep all indexes up to date. This could impact peformance as each save will trigger the indexing to occur.

The AUTO_UPDATE setting allows you to disable this for the backend:

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': ...,
        'AUTO_UPDATE': False,
    }
}

If you have disabled auto-update, you must run the rebuild_modelsearch_index command on a regular basis to keep the index in sync with the database.

`ATOMIC_REBUILD`

By default (when using the Elasticsearch backend), Django Modelsearch creates a new index when the rebuild_modelsearch_index is run, reindexes the content into the new index then, using an alias, activates the new index. Then deletes the old index.

If creating new indexes is not an option for you, you can disable this behaviour by setting ATOMIC_REBUILD to False. This will make Django Modelsearch delete the index then build a new one. Note that this will cause the search engine to not return results until the rebuild is complete.

`BACKEND`

Here’s a list of backends that Django Modelsearch supports out of the box.

Database Backend (default)

modelsearch.backends.database

The database search backend searches content in the database using the full-text search features of the database backend in use (such as PostgreSQL FTS, SQLite FTS5). This backend is intended to be used for development and also should be good enough to use in production on sites that don’t require any Elasticsearch specific features.

If you use the PostgreSQL database backend, you must add django.contrib.postgres to your INSTALLED_APPS setting.

PostgreSQL Configuration

The PostgreSQL backend supports additional configuration options:

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'modelsearch.backends.database.postgres.postgres',
        'SEARCH_CONFIG': 'english',  # PostgreSQL text search configuration
        'FUZZY_SIMILARITY_THRESHOLD': 0.3,  # Threshold for fuzzy search (default: 0.3)
        'FUZZY_PREFIX_BOOST': 0.0,  # Boost for prefix matches (default: 0.0)
    }
}

`SEARCH_CONFIG`

The PostgreSQL text search configuration to use. You can get available configurations using SELECT cfgname FROM pg_ts_config;.

Note that the text search configuration for autocomplete queries defaults to 'simple' to disable stemming, which provides better autocomplete results.

`FUZZY_SIMILARITY_THRESHOLD`

The minimum trigram similarity score (0.0 to 1.0) required for fuzzy search matches. Default is 0.3.

Higher values (e.g., 0.5) require closer matches, returning fewer but more precise results
Lower values (e.g., 0.1) allow more approximate matches, returning more results

`FUZZY_PREFIX_BOOST`

A bonus added to the similarity score when a field starts with the search query (case-insensitive). Default is 0.0 (disabled).

Set to a value like 0.2 to 0.5 to prioritize results where the field starts with the query
This helps rank “Python Guide” higher than “Learning Python” when searching for “Python”

Note

Fuzzy search requires PostgreSQL extensions. Use the provided management commands to enable what you need:

# Trigram similarity (required for the default trigram algorithm)
python manage.py enable_trigram

# Accent-insensitive matching (required for Fuzzy(unaccent=True))
python manage.py enable_unaccent

# Levenshtein distance (required for FUZZY_ALGORITHM = "levenshtein")
python manage.py enable_fuzzystrmatch

Elasticsearch/OpenSearch Backends

Elasticsearch versions 7, 8, and 9 are supported. OpenSearch 2 and 3 are supported.

You’ll need to install the elasticsearch-py package for Elasticsearch and for OpenSearch, you’ll need the opensearch-py package. The major version of the package must match the installed version of Elasticsearch/OpenSearch:

pip install "elasticsearch>=7,<8"  # for Elasticsearch 7.x

pip install "elasticsearch>=8,<9"  # for Elasticsearch 8.x

pip install "elasticsearch>=9,<10"  # for Elasticsearch 9.x

pip install "opensearch-py>=2,<3"  # for OpenSearch 2.x

pip install "opensearch-py>=3,<4"  # for OpenSearch 3.x

Then configure the backend in MODELSEARCH_SETTINGS 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)

Any defined key in OPTIONS is passed directly to the Elasticsearch/OpenSearch constructor as a case-sensitive keyword argument (for example 'max_retries': 1).

A username and password may be optionally supplied to the URL field to provide authentication credentials for the Elasticsearch/OpenSearch service:

MODELSEARCH_BACKENDS = {
    'default': {
        ...
        'URLS': ['https://username:password@localhost:9200'],
        ...
    }
}

INDEX_SETTINGS is a dictionary used to override the default settings to create the index. The default settings are defined inside the ElasticsearchSearchBackend class in the module modelsearch/backends/elasticsearch7.py. Any new key is added and any existing key, if not a dictionary, is replaced with the new value. Here’s a sample of how to configure the number of shards and set the Italian LanguageAnalyzer as the default analyzer:

MODELSEARCH_BACKENDS = {
    'default': {
        ...,
        'INDEX_SETTINGS': {
            'settings': {
                'index': {
                    'number_of_shards': 1,
                },
                'analysis': {
                    'analyzer': {
                        'default': {
                            'type': 'italian'
                        }
                    }
                }
            }
        }
    }

If you prefer not to run an Elasticsearch server in development or production, there are many hosted services available, including Bonsai, which offers a free account suitable for testing and development. To use Bonsai:

Sign up for an account at Bonsai
Use your Bonsai dashboard to create a Cluster.
Configure URLS in the Elasticsearch entry in MODELSEARCH_BACKENDS using the Cluster URL from your Bonsai dashboard
Run ./manage.py rebuild_modelsearch_index

Amazon AWS OpenSearch

The OpenSearch backend is compatible with Amazon OpenSearch Service, but requires additional configuration to handle IAM based authentication. This can be done with the requests-aws4auth package along with the following configuration:

from elasticsearch import RequestsHttpConnection
from requests_aws4auth import AWS4Auth

MODELSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'modelsearch.backends.opensearch2',
        'INDEX_PREFIX': 'test_',
        'TIMEOUT': 5,
        'HOSTS': [{
            'host': 'YOURCLUSTER.REGION.es.amazonaws.com',
            'port': 443,
            'use_ssl': True,
            'verify_certs': True,
            'http_auth': AWS4Auth('ACCESS_KEY', 'SECRET_KEY', 'REGION', 'es'),
        }],
        'OPTIONS': {
            'connection_class': RequestsHttpConnection,
        },
    }
}

Rolling Your Own

See Custom backends.

Backends

AUTO_UPDATE

ATOMIC_REBUILD

BACKEND