Semantic search for Django

Vector search that
traverses your model graph

Make a Product searchable by its category__name, tags__name and brand__description — automatically. Sentence-transformers embeddings, pluggable vector backends, admin UI and REST API out of the box.

Get started View on GitHub PyPI

# ChromaDB backend (recommended for local/dev)

pip install django-graph-search[chromadb]

# or FAISS / Qdrant / pgvector / cloud embeddings

pip install django-graph-search[faiss] # qdrant · pgvector · openai · cohere · all

Why graph search?

Most Django search solutions treat each model in isolation. Django Graph Search builds rich search context by walking the ORM relation graph before indexing.

🕸️

Graph-aware indexing

Follows FK, M2M and reverse relations to a configurable depth, with per-field weights and traversal limits (MAX_RELATED_ITEMS, MAX_TEXT_LENGTH).

🌐

Multilingual semantics

Sentence-transformers embeddings out of the box; OpenAI and Cohere cloud embeddings when you don't want PyTorch in your workers.

🔌

Pluggable backends

ChromaDB, FAISS, Qdrant, pgvector — one interface, upsert semantics everywhere. Switch with a single settings key.

⚡

Transaction-safe auto-index

Signals dispatch via transaction.on_commit into a bounded daemon thread pool, Celery or django-q — requests never block.

🧭

Admin & REST included

Semantic search inside /admin/, index-coverage dashboard, and a REST API with permissions, throttling and streaming.

💬

Conversational & LangGraph

Optional session-aware search with clarification loops, query expansion, reranking and SSE/NDJSON event streaming.

Quickstart

Three steps to semantic search across your models.

# 1. settings.py
INSTALLED_APPS = [ ..., "django_graph_search" ]

GRAPH_SEARCH = {
    "MODELS": [
        {"model": "shop.Product",
         "fields": ["name", "description", "category__name", "tags__name"]},
    ],
    "VECTOR_STORE": {
        "BACKEND": "django_graph_search.backends.ChromaDBBackend",
        "OPTIONS": {"persist_directory": "vector_db"},
    },
}

# 2. urls.py
urlpatterns = [ path("api/search/", include("django_graph_search.urls")) ]

# 3. build the index and query
$ python manage.py build_search_index
$ curl "http://localhost:8000/api/search/?q=red+phone&limit=5"

Supported backends

Same API, same document format — pick per environment. All backends re-index with upsert semantics since 0.3.4.

Backend	Best for	Server required
ChromaDB	Development, small-medium datasets	No
FAISS	High-speed CPU search, offline, optional disk persistence	No
Qdrant	Production, large datasets, filtering	Yes
pgvector	Same PostgreSQL as Django, no separate vector server	PostgreSQL + `vector`

What's new in 0.3.6

Bug-fix & security release. Rebuild your index after upgrading.

Indexed-text leak closed — with follow_relations=True unlisted fields of the root object (e.g. the auth.User password hash) no longer end up in the index or in the REST text field; password is never indexed
Qdrant backend actually works — UUID5 point ids, correct distance resolution ("Cosine" used to raise), query_points on modern clients
LANGGRAPH.TIMEOUT_SECONDS enforced — hard limit around every LLM call with fallback to deterministic search
Fewer 500s — /similar/ returns 404/400 for unknown model / invalid pk; stale index entries, UUID primary keys and a missing django.contrib.admin no longer crash
Faster result hydration — one pk__in query per model instead of one per hit
Real-client integration tests — Qdrant :memory:, ChromaDB, FAISS end-to-end (no Docker)
CI matrix — Python 3.10–3.13 × Django 4.2/5.1/5.2/6.0, 160+ tests, pylint 10/10, mypy clean

Full release notes →

Vector search thattraverses your model graph