Metadata-Version: 2.4
Name: modelsearch
Version: 1.1.1
Summary: A library for indexing Django models with Elasicsearch, OpenSearch or database and searching them with the Django ORM.
Author-email: Wagtail core team + contributors <hello@wagtail.org>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/wagtail/django-modelsearch
Project-URL: Documentation, https://django-modelsearch.readthedocs.io/en/latest
Project-URL: Source, https://github.com/wagtail/django-modelsearch
Project-URL: Repository, https://github.com/wagtail/django-modelsearch
Project-URL: Issues, https://github.com/wagtail/django-modelsearch/issues
Project-URL: Changelog, https://github.com/wagtail/django-modelsearch/releases
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: django-tasks<0.10,>=0.7
Provides-Extra: test
Requires-Dist: dj-database-url<3,>=2.3.0; extra == "test"
Requires-Dist: psycopg<4,>=3.2.6; extra == "test"
Requires-Dist: mysqlclient<3,>=2.2.0; extra == "test"
Requires-Dist: django-modelcluster<7,>=6.4; extra == "test"
Requires-Dist: django-tasks<1,>=0.6.1; extra == "test"
Requires-Dist: django-taggit<7,>=6.1.0; extra == "test"
Requires-Dist: coverage<8,>=7.10.6; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=8.2.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4.0,>=3.0.2; extra == "docs"
Requires-Dist: myst-parser<5,>=4.0.1; extra == "docs"
Provides-Extra: dev
Requires-Dist: ruff==0.13.0; extra == "dev"
Requires-Dist: pre-commit==3.4.0; extra == "dev"
Dynamic: license-file

# Django ModelSearch

<p>
    <a href="https://github.com/wagtail/django-modelsearch/actions">
        <img src="https://github.com/wagtail/django-modelsearch/workflows/ModelSearch%20CI/badge.svg?branch=main" alt="Build Status" />
    </a>
    <a href="https://opensource.org/licenses/BSD-3-Clause">
        <img src="https://img.shields.io/badge/license-BSD-blue.svg" alt="License" />
    </a>
    <a href="https://pypi.python.org/pypi/modelsearch/">
        <img src="https://img.shields.io/pypi/v/modelsearch.svg" alt="Version" />
    </a>
    <a href="https://django-modelsearch.readthedocs.io/en/latest/">
        <img src="https://img.shields.io/badge/Documentation-blue" alt="Documentation" />
    </a>
</p>

Django ModelSearch allows you to index Django models and [search them using the ORM](https://django-modelsearch.readthedocs.io/en/latest/searching.html)!

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](https://django-modelsearch.readthedocs.io/en/latest/searching.html#autocomplete-search)
- [Faceting](https://django-modelsearch.readthedocs.io/en/latest/searching.html#facet-field-name)
- [Per-field boosting](https://django-modelsearch.readthedocs.io/en/latest/indexing.html#boosting-search-fields)
- [Fuzzy Search](https://django-modelsearch.readthedocs.io/en/latest/searching.html#fuzzy-search)
- [Phrase search](https://django-modelsearch.readthedocs.io/en/latest/searching.html#phrase-search)
- [Structured queries](https://django-modelsearch.readthedocs.io/en/latest/searching.html#structured-queries)
- [Multi-table inheritance](https://django-modelsearch.readthedocs.io/en/latest/indexing.html#indexing-models-with-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](https://github.com/wagtail/wagtail) since 2014 and extracted into a separate package in March 2025.

## Installation

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

```shell
pip install modelsearch
```

```python
# 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`](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-INSTALLED_APPS) setting.

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

```python
# 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`:

```python
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!

```python
Song.objects.search("Flying Whales")
```

Searches also work when reversing `ForeignKey`s:

```python
opeth.songs.search("Harvest")
```

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

```python
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.
