redis-search-django

Index Django models into Redis Query Engine (RediSearch) and query them with the same lookups you already use in the ORM.

Django stays the source of truth. You declare a Document, signals (or redisearch populate) keep a search copy in Redis, and you query with Document.objects.filter(...).

Documentation: https://saadmk11.github.io/redis-search-django/ · Getting started · Demo app · Contribute

Features

• Declarative documents — one Document class per model, auto-discovered from documents.py
• Live sync — create / update / delete (including related FK, O2O, and M2M) update Redis automatically
• Nested data — fields.Object and fields.Nested for related rows (JSON or HASH storage)
• Django-style query — filter, exclude, search, Q, order_by, stock Paginator
• ORM hand-off — to_queryset() returns Django rows in RediSearch rank order
• Facets and aggregates — .facets() and a first-class Aggregate builder over FT.AGGREGATE
• Vector search — embed on save with a pluggable function, then knn() next to filter()
• Async — acount, aget, ato_queryset, async index writes, and async views
• Index lifecycle — redisearch for create, update, populate, rebuild, blue-green reindex, and verify
• Debug overlay — optional per-view Redis query / write inspector (SearchDebugMixin)
• Queues without a dependency — swap SIGNAL_PROCESSOR to run the same writes in Celery, django-q, or RQ

Requirements

Quick start

uv add redis-search-django
# or
pip install redis-search-django

# settings.py
INSTALLED_APPS = [
    ...,
    "redis_search_django",
]

# Optional. Default is redis://localhost:6379/0
REDIS_SEARCH = {
    "URL": "redis://localhost:6379/0",
}

This repo’s Compose file starts Redis Stack (6379) and Redis Insight (8001):

docker compose up -d

Declare a document in documents.py so the app can discover it:

# shop/documents.py
from redis_search_django.documents import Document

from .models import Product


class ProductDocument(Document):
    class Django:
        model = Product
        fields = ["name", "description", "price", "available"]

Create the index and load existing rows:

python manage.py redisearch create
python manage.py redisearch populate

Search:

from redis_search_django import Q
from shop.documents import ProductDocument

hits = ProductDocument.objects.filter(
    Q(name__search="shoes") | Q(description__search="shoes"),
    price__lte=150,
    available=True,
)[:20]

for hit in hits:
    hit.pk, hit.score, hit.name

Use redis_search_django.Q, not django.db.models.Q. Full walkthrough: Getting started.

Query API

DocumentQuerySet is lazy and clone-on-write, like Django.

Lookups, pagination, and views: Query. Vector fields and knn(): Vector search.

Indexing

Details: Indexing. Upgrading from 0.1: Migrate.

Example app

example/ is a catalog you can click through — search, KNN, aggregations, async, and CRUD. How to run it and what each page is: Demo app.

Development

uv sync --group dev
docker compose up -d
uv run pytest

How to run linters, the matrix, and open a PR: Contribute.

License

MIT