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.4

Reliability & security hardening — fully backward-compatible with 0.3.x.

Upsert semantics on every backend — re-saving an object can no longer raise DuplicateIDError or create duplicates
Transaction-safe signals — indexing and deletion run via transaction.on_commit; rollback can't corrupt the index
/api/search/similar/ access control — now enforces the same permissions and throttling as other endpoints
FAISS persistence — save the index to disk with persist_path, reload on startup
Graph traversal limits — MAX_RELATED_ITEMS and MAX_TEXT_LENGTH guard against runaway indexing
Filtered searches fill limit — model filters are pushed into the vector store; find_similar excludes the object itself
Result field whitelist — REST data exposes only fields from your model config
CI matrix — Python 3.10–3.13 × Django 4.2/5.0/5.1, 131 tests, pylint 10/10

Full release notes →

Vector search thattraverses your model graph