Registry / database / django-modelsearch

django-modelsearch

JSON →
library1.2.0pypypiunverified

django-modelsearch is a Python library that enables indexing Django models with various search backends, including Elasticsearch, OpenSearch, and the database itself (PostgreSQL, MySQL). It provides a unified API for searching models, inspired by Wagtail Search. The current version is 1.2.0, with releases occurring periodically to support Django and backend updates.

pip install django-modelsearch
INSTALL
IMPORT
SIG · DJANGO-MODELSEARCH
D
django-modelsearch
databasepythonv1.2.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
build_error
glibc
py 3.103.915 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Index
from modelsearch.base import Index
SearchField
from modelsearch.fields import SearchField
MatchAll
from modelsearch.query import MatchAll
ElasticsearchSearchBackend
from modelsearch.backends.elasticsearch import ElasticsearchSearchBackend
from modelsearch.backends import ElasticsearchSearchBackend
Backend classes are nested within submodules like `modelsearch.backends.elasticsearch` or `modelsearch.backends.database`

Define a Django model with an inner `Search` class that specifies fields to index. Configure `MODELSEARCH_BACKENDS` in your Django settings. Use the `search()` method on your model's manager to query the index. Remember to run `manage.py update_index` after defining models or changing their data to populate the search index.

import os from django.db import models from modelsearch.base import Index from modelsearch.fields import SearchField from modelsearch.query import MatchAll from django.conf import settings # Minimal Django settings setup for quickstart, typically in settings.py if not settings.configured: settings.configure( INSTALLED_APPS=[ "modelsearch", "django.contrib.postgres" # For PostgreSQL DB search features ], MODELSEARCH_BACKENDS={ "default": { "BACKEND": "modelsearch.backends.database.DatabaseSearchBackend" # "BACKEND": "modelsearch.backends.elasticsearch.ElasticsearchSearchBackend", # "URLS": [os.environ.get('ELASTICSEARCH_URL', 'http://localhost:9200')], # "INDEX": "test_modelsearch", } }, DATABASES={ "default": { "ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:", } }, SECRET_KEY="dummy-secret-key" ) # Define a Django Model class Article(models.Model): title = models.CharField(max_length=255) body = models.TextField() class Search(Index): fields = [ SearchField("title", boost=10), SearchField("body"), ] def __str__(self): return self.title # Example usage (run after Django setup and migrations) # This part assumes a database is configured and tables are created. # For a real application, you'd run `manage.py migrate` and then `manage.py update_index`. if __name__ == "__main__": # In a real Django project, you'd import Article and use its manager. # For this isolated example, we simulate object creation. # Note: Search index update requires running `manage.py update_index` or calling backend manually. print("Quickstart will only demonstrate search query structure.") print("To run fully, ensure Django is setup, migrated, and index updated.") # Example search (using a dummy queryset for demonstration) # In a real app, this would be: `Article.objects.search("search term")` search_query = "example" # Simulate a search call class MockSearchManager: def search(self, query): print(f"Searching for: {query}") return ["MockResult1", "MockResult2"] mock_manager = MockSearchManager() print(f"\nSearch for '{search_query}':") results = mock_manager.search(search_query) print(f"Results: {results}") print("\nSearch for all with MatchAll():") results_all = mock_manager.search(MatchAll()) print(f"Results: {results_all}")
Debug
Known issues
breakingSupport for OpenSearch 1.x was dropped in version 1.1, which aligns with OpenSearch's End-of-Life for that series. Users on OpenSearch 1.x must upgrade their OpenSearch cluster or use an older version of django-modelsearch (pre-1.1).
fix
Upgrade your OpenSearch cluster to version 2.x or later, or downgrade `django-modelsearch` to a version prior to 1.1 if upgrading OpenSearch is not an option.
affects: >=1.1
breakingVersion 1.0 was a fork from Wagtail's internal search module. If you are migrating from an older Wagtail project that used its built-in search before this fork, direct migration might require adjustments to settings and index definitions, as some internal paths or configurations may have changed.
fix
Carefully review your `MODELSEARCH_BACKENDS` settings and model `Search` class definitions. Re-indexing your data after upgrading is highly recommended (`python manage.py update_index`).
affects: >=1.0
deprecatedThe hidden setting `_WAGTAILSEARCH_FORCE_AUTO_UPDATE` was removed in version 1.1.1. While not a public API, any reliance on this internal setting will cease to function.
fix
Remove the `_WAGTAILSEARCH_FORCE_AUTO_UPDATE` setting from your configuration. If its functionality was critical, you may need to implement similar logic manually or adjust your indexing strategy.
affects: >=1.1.1
gotchaFor PostgreSQL database search and certain ORM features (like `SearchVector`), you must include `django.contrib.postgres` in your `INSTALLED_APPS`.
fix
Add `'django.contrib.postgres'` to your `INSTALLED_APPS` list in `settings.py`.
affects: all
gotchaConfiguring search backends (`MODELSEARCH_BACKENDS`) correctly is crucial. Misconfigurations can lead to indexing failures or incorrect search results without immediate errors. Pay close attention to backend types, URLs, and index names.
fix
Thoroughly review the `MODELSEARCH_BACKENDS` documentation for your chosen backend (Elasticsearch, OpenSearch, or Database). Ensure URLs are correct, indices exist (or are created), and permissions are set up correctly for your backend service.
affects: all
Upgrade
Version history
1.2.0latest on PyPI
Audit
Dependencies
DjangorequiredFramework integration for models and ORM
elasticsearchoptionalRequired for Elasticsearch search backend
opensearch-pyoptionalRequired for OpenSearch search backend
psycopg2-binaryoptionalIndirectly required by django.contrib.postgres for PostgreSQL database features if not using other psycopg2 drivers
Agent activity
8 hits · last 30 days
node
6
Resources

No resource links recorded.