django-icv-search

Search for Django without the lock-in. Point it at Meilisearch, PostgreSQL, or your own backend: the same service API, filters, and query builder work across all of them. Swap engines without rewriting application code.

Why this over the alternatives?

Over the raw Meilisearch SDK: you get Django-native filters (price__gte=10), auto-indexing on model save, zero-downtime reindexing, Celery integration, search analytics, and a merchandising layer, none of which the SDK provides.

Over django-haystack: modern async-capable HTTP client (httpx), swappable backends without engine-specific query syntax, built-in multi-tenancy, and a merchandising pipeline for controlling result presentation, all with a much smaller footprint.

Over both: one consistent service API regardless of backend, normalised response dataclasses that insulate your code from engine-specific shapes, and a DummyBackend for fast, deterministic tests without a running search engine.

Requirements

• Python 3.11+
• Django 5.1+

Features

Core

• Swappable backends modelled on Django's email backend pattern: change one setting, no application code changes
• Django-native filter dicts and sort lists translated to each engine's syntax automatically
• Normalised SearchResult, TaskResult, and IndexStats dataclasses insulate your code from engine-specific response shapes
• SearchableMixin: declare a model as indexable with a handful of class attributes
• Auto-indexing via post_save / post_delete signals; disable per-block with skip_index_update()
• SearchQuery fluent builder: .text().filter().sort().facets().highlight().geo_near().execute()
• ICVSearchPaginator: uses estimated_total_hits from the engine; no extra COUNT query

Backends

• Meilisearch: default; uses httpx directly, keeping dependencies minimal
• PostgreSQL: zero-infrastructure full-text search using tsvector and ts_rank; no external service needed
• DummyBackend: in-memory backend for fast, deterministic tests
• Custom backends: subclass BaseSearchBackend and implement the abstract interface

Indexing and index management

• Create, configure, sync, and delete indexes; Django is the source of truth
• Zero-downtime reindex: builds a temp index, then atomically swaps with the live one
• Celery integration for async indexing with exponential backoff; degrades gracefully to synchronous when Celery is absent
• Signal debouncing: batches rapid saves into a single indexing call
• Soft-delete awareness: auto-excludes soft-deleted records on reindex and removes them on save
• Management commands: icv_search_setup, icv_search_health, icv_search_sync, icv_search_reindex, icv_search_create_index, icv_search_clear

Query features

• Facet distribution: normalised facet_distribution dict with get_facet_values() helper
• Range filters: __gte, __gt, __lte, __lt suffixes work across all backends
• Highlighting: formatted_hits with custom pre/post tags; native on Meilisearch, ts_headline() on PostgreSQL
• Ranking scores: _rankingScore on Meilisearch, ts_rank on PostgreSQL, term-frequency on Dummy
• Geo-distance search: filter and sort by proximity; native _geoRadius on Meilisearch, Haversine on others
• Multi-search: execute multiple queries in one request
• Synonym, stop-word, and typo-tolerance management

Analytics

• SearchQueryLog per-query logging and SearchQueryAggregate daily rollups
• Three logging strategies: individual, aggregate, or both; sample rate control for high-traffic sites
• get_popular_queries(), get_zero_result_queries(), get_search_stats(), get_query_trend()
• get_trending_searches() and get_suggested_queries() from existing aggregate data: no external service needed

Merchandising (optional)

• Query redirects, query rewrites, pinned results, boost rules, search banners, and zero-result fallbacks
• 9-step merchandised_search() pipeline; each step is individually skippable
• Rule scheduling with starts_at / ends_at windows; database-cached rule loading
• Django admin with bulk enable/disable actions and hit count tracking
• Gated behind ICV_SEARCH_MERCHANDISING_ENABLED; when disabled, merchandised_search() delegates directly to search()

Infrastructure

• Multi-tenancy: tenant-prefixed index names via a configurable callable; no coupling to any tenant model
• Result caching via Django's cache framework; automatic invalidation on index changes
• Health check endpoint (/health/) for load balancer probes
• Django signals for index lifecycle events (search_index_created, documents_indexed, etc.)
• icv_search.testing: fixtures, factories, and helpers for consuming projects

Installation

Basic

pip install django-icv-search

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "icv_search",
]

Run migrations:

python manage.py migrate icv_search

With icv-core

Installing with the icv-core extra gives you BaseModel (UUID primary key plus created_at / updated_at timestamps) from django-icv-core:

pip install "django-icv-search[icv-core]"

INSTALLED_APPS = [
    # ...
    "icv_core",
    "icv_search",
]

Both SearchIndex and IndexSyncLog inherit from icv_core.models.BaseModel automatically when icv_core is present.

Quick Start

# settings.py
ICV_SEARCH_BACKEND = "icv_search.backends.meilisearch.MeilisearchBackend"
ICV_SEARCH_URL = "http://localhost:7700"
ICV_SEARCH_API_KEY = "your-meilisearch-master-key"

# 1. Make your model searchable
# myapp/models.py
from django.db import models
from icv_search.mixins import SearchableMixin

class Article(SearchableMixin, models.Model):
    search_index_name = "articles"
    search_fields = ["title", "body"]
    search_filterable_fields = ["published", "author_id"]
    search_sortable_fields = ["published_at", "title"]

    title = models.CharField(max_length=200)
    body = models.TextField()
    author_id = models.IntegerField()
    published = models.BooleanField(default=False)
    published_at = models.DateTimeField(null=True)

# 2. Create the index (run once, e.g. in a migration or management command)
from icv_search.services import create_index
index = create_index("articles", model_class=Article)

# 3. Index documents
from icv_search.services import index_documents
index_documents("articles", [
    {"id": "1", "title": "Django tips", "body": "...", "published": True},
    {"id": "2", "title": "Search patterns", "body": "...", "published": True},
])

# 4. Search
from icv_search.services import search
results = search("articles", "django", limit=10)
for hit in results.hits:
    print(hit["title"])

Configuration

Settings Reference

All settings are namespaced under ICV_SEARCH_*. Every setting has a sensible default so the package works out of the box for local development.

Auto-Indexing Configuration

ICV_SEARCH_AUTO_INDEX wires post_save and post_delete signal handlers automatically for any model you declare. The package's AppConfig.ready() reads this setting and connects the handlers on startup.

ICV_SEARCH_AUTO_INDEX = {
    "articles": {
        "model": "blog.Article",
        "on_save": True,
        "on_delete": True,
        "async": True,
        "should_update": "blog.search.should_index_article",
    },
    "products": {
        "model": "catalogue.Product",
        "async": False,  # Synchronous for this index
    },
}

# blog/search.py
def should_index_article(instance) -> bool:
    """Only index published articles."""
    return instance.published

SearchableMixin

Add SearchableMixin to any Django model to make it indexable. Declare the index configuration as class attributes.

from django.db import models
from icv_search.mixins import SearchableMixin

class Product(SearchableMixin, models.Model):
    search_index_name = "products"
    search_fields = ["name", "description", "sku"]
    search_filterable_fields = ["category_id", "is_active", "price"]
    search_sortable_fields = ["price", "created_at", "name"]

    name = models.CharField(max_length=200)
    description = models.TextField()
    sku = models.CharField(max_length=50, unique=True)
    category_id = models.IntegerField()
    price = models.DecimalField(max_digits=10, decimal_places=2)
    is_active = models.BooleanField(default=True)
    created_at = models.DateTimeField(auto_now_add=True)

Customising the document representation

Override to_search_document() to control exactly what is sent to the engine:

def to_search_document(self) -> dict:
    return {
        "id": str(self.id),
        "name": self.name,
        "description": self.description,
        "sku": self.sku,
        "price": float(self.price),          # Decimal -> float for JSON
        "category_id": self.category_id,
        "is_active": self.is_active,
        "category_name": self.category.name, # Denormalised for search
    }

Customising the reindex queryset

Override get_search_queryset() to control which records are included in a full reindex and to add select_related / prefetch_related for performance:

@classmethod
def get_search_queryset(cls):
    return (
        cls.objects
        .filter(is_active=True)
        .select_related("category")
    )

Service API

Import service functions from icv_search.services:

from icv_search.services import (
    # Index management
    create_index, delete_index, update_index_settings,
    get_index_settings, get_index_stats,
    # Synonym / stop-word / typo management
    get_synonyms, update_synonyms, reset_synonyms,
    get_stop_words, update_stop_words, reset_stop_words,
    get_typo_tolerance, update_typo_tolerance,
    # Index settings (1.0.0b1)
    get_displayed_attributes, update_displayed_attributes, reset_displayed_attributes,
    get_distinct_attribute, update_distinct_attribute,
    get_pagination_settings, update_pagination_settings,
    get_faceting_settings, update_faceting_settings,
    get_proximity_precision, update_proximity_precision,
    get_search_cutoff, update_search_cutoff,
    get_dictionary, update_dictionary, reset_dictionary,
    get_separator_tokens, update_separator_tokens, reset_separator_tokens,
    get_non_separator_tokens, update_non_separator_tokens, reset_non_separator_tokens,
    get_prefix_search, update_prefix_search,
    get_embedders, update_embedders, reset_embedders,
    get_localized_attributes, update_localized_attributes, reset_localized_attributes,
    get_ranking_rules, update_ranking_rules,
    # Document operations
    index_documents, remove_documents, delete_documents_by_filter,
    index_model_instances, reindex_all, reindex_zero_downtime,
    # Search
    search, multi_search, get_task,
    # Analytics
    get_popular_queries, get_zero_result_queries,
    get_search_stats, get_query_trend,
    clear_query_logs, clear_query_aggregates,
    # Utilities
    get_current_tenant_id, ICVSearchCache,
)

Index Management

create_index

Creates a SearchIndex record, provisions the index in the engine, and pushes any settings. If model_class is provided and uses SearchableMixin, its field lists seed the index settings automatically.

from icv_search.services import create_index
from myapp.models import Product

index = create_index(
    name="products",
    model_class=Product,
    settings={"rankingRules": ["words", "typo", "proximity"]},
)

delete_index

Deletes the SearchIndex record from Django and removes the index from the engine. Raises SearchBackendError on engine failure.

from icv_search.services import delete_index
delete_index("products")

update_index_settings

Merges settings into the existing index, saves to Django, and syncs to the engine:

from icv_search.services import update_index_settings
update_index_settings("products", {
    "synonyms": {"phone": ["mobile", "handset"]},
})

get_index_stats

Returns a normalised IndexStats dataclass with live data from the engine:

from icv_search.services import get_index_stats
stats = get_index_stats("products")
print(stats.document_count)
print(stats.is_indexing)

Document Operations

index_documents

from icv_search.services import index_documents
result = index_documents("products", [
    {"id": "abc123", "name": "Widget", "price": 9.99},
    {"id": "def456", "name": "Gadget", "price": 24.99},
])
print(result.task_uid)

remove_documents

from icv_search.services import remove_documents
remove_documents("products", ["abc123", "def456"])

index_model_instances

Indexes model instances using their SearchableMixin configuration. Iterates the queryset in batches. Returns the total documents indexed.

from icv_search.services import index_model_instances
from myapp.models import Product

count = index_model_instances(Product, batch_size=500)
print(f"Indexed {count} products")

reindex_all

Full reindex: clears all existing documents, then re-indexes from get_search_queryset().

from icv_search.services import reindex_all
total = reindex_all("products", Product, batch_size=500)

reindex_zero_downtime

Creates a temporary index, populates it from the model queryset, then atomically swaps with the live index. Falls back to reindex_all() if the backend does not support index swaps.

from icv_search.services import reindex_zero_downtime
total = reindex_zero_downtime("products", Product, batch_size=500)

Search

Filters and sort orders use Django-native syntax. The service layer translates them to each engine's format automatically, so the same calling code works across all backends.

from icv_search.services import search

# Django-native filter dict and sort list
result = search(
    "products",
    "padel",
    filter={"city": "Madrid", "is_active": True, "price__lt": 200},
    sort=["-created_at"],
    limit=10,
)

for hit in result.hits:
    print(hit["name"], hit["price"])

print(f"About {result.estimated_total_hits} results")

Pagination

ICVSearchPaginator uses estimated_total_hits as the count instead of running a separate queryset.count() query:

from icv_search import ICVSearchPaginator
from icv_search.services import search

page_number = int(request.GET.get("page", 1))
per_page = 25
result = search("products", query, limit=per_page, offset=(page_number - 1) * per_page)

paginator = ICVSearchPaginator(result, per_page=per_page)
page_obj = paginator.get_page(page_number)

{% for hit in page_obj %}{{ hit.name }}{% endfor %}

{% if page_obj.is_estimated %}
    {{ page_obj.display_count }} results
{% else %}
    {{ page_obj.paginator.count }} results
{% endif %}

Facets

result = search("products", "shoes", facets=["brand", "colour"])
print(result.facet_distribution)
# {"brand": {"Nike": 42, "Adidas": 31}, "colour": {"black": 55, "white": 28}}

for facet in result.get_facet_values("brand"):
    print(f"{facet['name']}: {facet['count']}")

Range Filters

Use Django-style lookup suffixes for numeric range queries. Supported suffixes: __gte (>=), __gt (>), __lte (<=), __lt (<). Works across all backends.

result = search("products", "",
    filter={"price__gte": 10, "price__lte": 100, "is_active": True},
)

Bulk Operations

skip_index_update is a context manager that temporarily disables auto-indexing signal handlers. Use it in bulk imports, data migrations, and test factories.

from icv_search.auto_index import skip_index_update

articles = [Article(title=f"Article {i}") for i in range(1000)]

with skip_index_update():
    Article.objects.bulk_create(articles)

# Trigger a single reindex after the bulk operation
from icv_search.services import reindex_all
reindex_all("articles", Article)

The context manager is nestable. Auto-indexing resumes when the outermost with block exits.

Highlighting

result = search("articles", "django tips",
    highlight_fields=["title", "body"],
    highlight_pre_tag="<mark>",
    highlight_post_tag="</mark>",
)

for hit in result.get_highlighted_hits():
    print(hit["title"])  # "...about <mark>Django</mark> <mark>tips</mark>..."

Works across all backends: Meilisearch uses native _formatted, PostgreSQL uses ts_headline(), DummyBackend wraps matching substrings.

Ranking Scores

result = search("products", "shoes", show_ranking_score=True)

for i, hit in enumerate(result.hits):
    hit, score = result.get_hit_with_score(i)
    print(f"{hit['name']}: {score:.2f}")

Meilisearch returns _rankingScore (0.0 to 1.0), PostgreSQL uses ts_rank, DummyBackend computes term-frequency.

Geo-Distance Search

result = search("restaurants", "",
    geo_point=(51.5074, -0.1278),  # London (lat, lng)
    geo_radius=5000,                # metres
    geo_sort="asc",                 # nearest first
)

for hit in result.hits:
    print(f"{hit['name']}: {hit.get('_geoDistance')}m away")

Declare geo fields on the mixin:

class Restaurant(SearchableMixin, models.Model):
    search_index_name = "restaurants"
    search_fields = ["name", "cuisine"]
    search_lat_field = "latitude"
    search_lng_field = "longitude"

    latitude = models.FloatField()
    longitude = models.FloatField()

Multi-Search

from icv_search.services import multi_search

results = multi_search([
    {"index_name": "products", "query": "shoes", "limit": 5},
    {"index_name": "articles", "query": "shoes", "limit": 3, "facets": ["category"]},
])

product_results, article_results = results

Meilisearch uses the native POST /multi-search endpoint. Other backends execute queries sequentially.

Synonym and Stop-Word Management

from icv_search.services import (
    get_synonyms, update_synonyms, reset_synonyms,
    get_stop_words, update_stop_words, reset_stop_words,
    get_typo_tolerance, update_typo_tolerance,
)

update_synonyms("products", {"phone": ["mobile", "handset"], "laptop": ["notebook"]})
update_stop_words("products", ["the", "a", "an"])
update_typo_tolerance("products", {"enabled": True, "minWordSizeForTypos": {"oneTypo": 4}})

SearchQuery Builder

A fluent API for constructing search queries:

from icv_search import SearchQuery

results = (
    SearchQuery("products")
    .text("running shoes")
    .filter(brand="Nike", price__gte=50)
    .sort("-price", "name")
    .facets("brand", "category")
    .highlight("name", "description")
    .geo_near(lat=51.5, lng=-0.12, radius=5000)
    .with_ranking_scores()
    .limit(20)
    .execute()
)

# Or get a paginator directly
paginator = SearchQuery("products").text("shoes").limit(25).paginate()
page = paginator.get_page(1)

Hybrid and Semantic Search

Hybrid search blends keyword and vector results in a single query. To use it, first configure an embedder on the index.

Configure embedders

from icv_search.services import update_embedders

# OpenAI embedder
update_embedders("products", {
    "default": {
        "source": "openAi",
        "apiKey": "sk-...",
        "model": "text-embedding-3-small",
        "dimensions": 1536,
    }
})

# Self-hosted via Ollama
update_embedders("products", {
    "local": {
        "source": "ollama",
        "url": "http://localhost:11434/api/embeddings",
        "model": "nomic-embed-text",
        "dimensions": 768,
    }
})

# User-provided vectors (pass the vector at search time)
update_embedders("products", {
    "custom": {
        "source": "userProvided",
        "dimensions": 512,
    }
})

Hybrid search via SearchQuery

results = (
    SearchQuery("products")
    .text("running shoes")
    .hybrid(semantic_ratio=0.5, embedder="default")
    .limit(20)
    .execute()
)

semantic_ratio controls the blend: 0.0 is pure keyword, 1.0 is pure semantic.

Pure vector search

Pass a raw embedding to query by vector alone (no keyword component):

import numpy as np

embedding = embed_text("comfortable running shoe")  # your embedder call

results = (
    SearchQuery("products")
    .vector(embedding)
    .limit(20)
    .execute()
)

Include vectors in results

Call .retrieve_vectors() to have _vectors returned on each hit:

results = (
    SearchQuery("products")
    .text("shoes")
    .hybrid(semantic_ratio=0.7)
    .retrieve_vectors()
    .execute()
)

for hit in results.hits:
    print(hit.get("_vectors"))

Hybrid and vector search are Meilisearch-only. PostgreSQL and DummyBackend silently ignore these parameters.

Snippet Cropping

Cropping returns short excerpts containing the match terms, with a configurable word budget and boundary marker. Cropped text appears in formatted_hits alongside highlighted content.

result = search("articles", "django tips",
    crop_fields=["body"],
    crop_length=20,          # words per excerpt
    crop_marker="...",       # boundary marker
)

for hit in result.get_highlighted_hits():
    print(hit["body"])  # "...about <mark>Django</mark> <mark>tips</mark>..."

Via SearchQuery:

results = (
    SearchQuery("articles")
    .text("django tips")
    .crop("body", length=20, marker="…")
    .execute()
)

Cropping is Meilisearch-only. Other backends ignore crop_fields, crop_length, and crop_marker.

Page-Based Pagination

Use page-based pagination (page + hits_per_page) instead of offset-based (limit + offset) when the engine returns exact totals. This gives access to total_hits and total_pages on SearchResult.

result = search("products", "shoes", page=2, hits_per_page=20)

print(result.page)          # 2
print(result.hits_per_page) # 20
print(result.total_hits)    # 143  (exact, not estimated)
print(result.total_pages)   # 8

Via SearchQuery:

results = (
    SearchQuery("products")
    .text("shoes")
    .page(2, per_page=20)
    .execute()
)

Note: page and hits_per_page are mutually exclusive with limit and offset; use one approach per query. Page-based mode is Meilisearch-only. The total_hits and total_pages fields on SearchResult are None when offset-based pagination is used.

To control the maximum result window, configure pagination.maxTotalHits on the index (default 1000):

from icv_search.services import update_pagination_settings
update_pagination_settings("products", max_total_hits=5000)

Geo Bounding Box and Polygon

Filter results to a rectangular or arbitrary geographic region.

Bounding box

# Only return results within a bounding box
result = search("restaurants", "",
    geo_bbox=((51.52, -0.08), (51.50, -0.14)),  # (top_right, bottom_left)
)

Via SearchQuery:

results = (
    SearchQuery("venues")
    .text("")
    .geo_bbox(top_right=(51.52, -0.08), bottom_left=(51.50, -0.14))
    .execute()
)

Polygon

result = search("properties", "",
    geo_polygon=[
        (51.52, -0.14),
        (51.52, -0.08),
        (51.50, -0.08),
        (51.50, -0.14),
    ],
)

Via SearchQuery:

results = (
    SearchQuery("properties")
    .geo_polygon([
        (51.52, -0.14),
        (51.52, -0.08),
        (51.50, -0.08),
        (51.50, -0.14),
    ])
    .execute()
)

Geo bounding box and polygon are Meilisearch-only. Use the existing .geo_near() method for radius-based geo search, which works across all backends.

Field Restriction

attributes_to_retrieve: limit returned fields

Reduce response payload by restricting which fields are returned in hits:

result = search("products", "shoes",
    attributes_to_retrieve=["id", "name", "price"],
)

The id field is always included regardless of the list. Via SearchQuery:

results = (
    SearchQuery("products")
    .text("shoes")
    .attributes_to_retrieve("id", "name", "price")
    .execute()
)

Supported on all backends. On PostgreSQL and DummyBackend the filtering is applied in Python after the search.

attributes_to_search_on: limit search scope

Restrict which fields are searched at query time, without modifying the index's permanent searchableAttributes configuration:

result = search("products", "nike",
    attributes_to_search_on=["name", "brand"],
)

Via SearchQuery:

results = (
    SearchQuery("products")
    .text("nike")
    .attributes_to_search_on("name", "brand")
    .execute()
)

attributes_to_search_on is Meilisearch-only.

Query-Time Distinct

Deduplicate results on a field at query time, without changing the index's permanent distinctAttribute setting:

result = search("products", "trainers", distinct="brand")

Via SearchQuery:

results = (
    SearchQuery("products")
    .text("trainers")
    .distinct("brand")
    .execute()
)

Only one document per brand value appears in results. Query-time distinct is Meilisearch-only.

To set distinct deduplication permanently at the index level, use update_distinct_attribute() instead.

Score Threshold and Details

Ranking score threshold

Exclude results whose relevance score falls below a minimum:

result = search("products", "shoes", ranking_score_threshold=0.5)

Via SearchQuery:

results = (
    SearchQuery("products")
    .text("shoes")
    .ranking_score_threshold(0.5)
    .execute()
)

Per-rule score details

Request a breakdown of how each ranking rule contributed to a hit's score:

result = search("products", "shoes", show_ranking_score_details=True)

for i, detail in enumerate(result.ranking_score_details):
    print(f"Hit {i}: {detail}")
# {"words": {"order": 0, "matchingWords": 1, "maxMatchingWords": 1, "score": 1.0}, ...}

Via SearchQuery:

results = (
    SearchQuery("products")
    .text("shoes")
    .show_ranking_score_details()
    .execute()
)

Match positions

Request byte-level offsets of matched terms in each hit:

result = search("articles", "django", show_matches_position=True)

for i, pos in enumerate(result.matches_position):
    print(f"Hit {i}: {pos}")
# {"title": [{"start": 0, "length": 6}], "body": [{"start": 42, "length": 6}]}

Via SearchQuery:

results = (
    SearchQuery("articles")
    .text("django")
    .show_matches_position()
    .execute()
)

ranking_score_threshold, show_ranking_score_details, and show_matches_position are Meilisearch-only.

Locale Support

Set ISO-639-3 language codes to tell the engine which language-specific tokeniser rules to apply for a given query. Useful when an index contains documents in multiple languages:

result = search("articles", "走る", locales=["jpn"])

Via SearchQuery:

results = (
    SearchQuery("articles")
    .text("走る")
    .locales("jpn")
    .execute()
)

To configure locale rules at the index level (which attributes map to which languages), use update_localized_attributes():

from icv_search.services import update_localized_attributes

update_localized_attributes("articles", [
    {"attributePatterns": ["title_ja", "body_ja"], "locales": ["jpn"]},
    {"attributePatterns": ["title_*"], "locales": ["eng"]},
])

Locale support is Meilisearch-only.

Delete by Filter

Remove documents matching a filter expression without knowing their IDs:

from icv_search.services import delete_documents_by_filter

# Engine-native filter string
result = delete_documents_by_filter("products", "is_active = false")

# Django-native filter dict (translated automatically)
result = delete_documents_by_filter("products", {"is_active": False})

print(result.task_uid)

Returns a TaskResult. The operation is asynchronous on Meilisearch; use get_task(result.task_uid) to poll for completion.

delete_documents_by_filter is Meilisearch-only. Calling it on PostgreSQL or DummyBackend raises SearchBackendError.

New Index Settings (1.0.0b1)

All settings functions follow the same three-function pattern: get_*, update_*, and (where applicable) reset_*. Import from icv_search.services.

Embedders

Configure vector embedding models for semantic and hybrid search:

from icv_search.services import get_embedders, update_embedders, reset_embedders

update_embedders("products", {
    "default": {
        "source": "openAi",
        "apiKey": "sk-...",
        "model": "text-embedding-3-small",
        "dimensions": 1536,
    }
})

current = get_embedders("products")
reset_embedders("products")  # removes all embedder config

Displayed attributes

Control which fields are returned in search results (index-level default):

from icv_search.services import (
    get_displayed_attributes,
    update_displayed_attributes,
    reset_displayed_attributes,
)

update_displayed_attributes("products", ["id", "name", "price", "image_url"])
reset_displayed_attributes("products")  # resets to ["*"] (all fields)

You can also declare search_displayed_fields on SearchableMixin to seed this setting from the model:

class Product(SearchableMixin, models.Model):
    search_displayed_fields = ["id", "name", "price", "image_url"]
    # ...

Distinct attribute (index-level)

Set permanent deduplication at the index level (as opposed to query-time .distinct()):

from icv_search.services import get_distinct_attribute, update_distinct_attribute

update_distinct_attribute("products", "brand")
update_distinct_attribute("products", None)  # disable
current = get_distinct_attribute("products")  # returns "brand" or None

Pagination settings

Control the hard cap on the result window for page-based pagination:

from icv_search.services import get_pagination_settings, update_pagination_settings

update_pagination_settings("products", max_total_hits=5000)
current = get_pagination_settings("products")
# {"maxTotalHits": 5000}

Faceting settings

Configure facet value limits and sort order:

from icv_search.services import get_faceting_settings, update_faceting_settings

update_faceting_settings("products", {
    "maxValuesPerFacet": 50,
    "sortFacetValuesBy": {
        "brand": "alpha",    # alphabetical
        "colour": "count",   # most-common first (default)
    },
})

Proximity precision

Trade ranking accuracy for indexing speed:

from icv_search.services import get_proximity_precision, update_proximity_precision

update_proximity_precision("products", "byAttribute")   # faster indexing
update_proximity_precision("products", "byWord")        # default: precise

Search cutoff

Set a per-index timeout (milliseconds) after which searches return partial results:

from icv_search.services import get_search_cutoff, update_search_cutoff

update_search_cutoff("products", 500)    # abort after 500 ms
update_search_cutoff("products", None)   # reset to default (1500 ms)

Custom dictionary

Declare multi-word strings that should be indexed and searched as single tokens:

from icv_search.services import get_dictionary, update_dictionary, reset_dictionary

update_dictionary("products", ["J. K. Rowling", "C++", "node.js"])

Separator and non-separator tokens

from icv_search.services import (
    update_separator_tokens, reset_separator_tokens,
    update_non_separator_tokens, reset_non_separator_tokens,
)

# Treat these characters as word boundaries
update_separator_tokens("products", ["|", "·"])

# Prevent these characters from splitting words
update_non_separator_tokens("products", ["-", "_"])

Prefix search

Control whether prefix matching is applied at indexing time:

from icv_search.services import get_prefix_search, update_prefix_search

update_prefix_search("products", "disabled")      # exact words only
update_prefix_search("products", "indexingTime")  # default

Localised attributes

Map attribute patterns to language codes for language-specific tokenisation:

from icv_search.services import (
    get_localized_attributes,
    update_localized_attributes,
    reset_localized_attributes,
)

update_localized_attributes("articles", [
    {"attributePatterns": ["title_ja", "body_ja"], "locales": ["jpn"]},
    {"attributePatterns": ["title_*"], "locales": ["eng"]},
])

Ranking rules

Customise the order in which ranking criteria are applied:

from icv_search.services import get_ranking_rules, update_ranking_rules

# Promote exact matches; deprioritise proximity
update_ranking_rules("products", [
    "words", "typo", "exactness", "proximity", "attribute", "sort",
])

current = get_ranking_rules("products")
# Default: ["words", "typo", "proximity", "attribute", "sort", "exactness"]

Complete settings function reference

Backend Support Matrix

Features marked Meilisearch-only are silently ignored on other backends unless noted otherwise.

Search Analytics

Enable query logging to track search behaviour:

# settings.py
ICV_SEARCH_LOG_QUERIES = True
ICV_SEARCH_LOG_MODE = "individual"  # or "aggregate" or "both"

from icv_search.services import (
    get_popular_queries,
    get_zero_result_queries,
    get_search_stats,
    get_query_trend,
)

# Most frequent queries in the last 7 days
popular = get_popular_queries("products", days=7, limit=20)

# Queries returning no results: find content gaps
gaps = get_zero_result_queries("products", days=7)

# Aggregate stats
stats = get_search_stats("products", days=7)
# {"total_queries": 1234, "avg_processing_time_ms": 12, "zero_result_rate": 0.05}

# Day-by-day trend
trend = get_query_trend("running shoes", "products", days=30)

All analytics functions read from the correct model automatically based on ICV_SEARCH_LOG_MODE.

Tenant Middleware

Auto-inject tenant context from the request instead of passing tenant_id on every call:

# settings.py
MIDDLEWARE = [
    # ...
    "icv_search.middleware.ICVSearchTenantMiddleware",
]
ICV_SEARCH_TENANT_PREFIX_FUNC = "myproject.search.get_tenant_prefix"

# In a view: tenant_id is injected automatically
results = search("products", "widget")

# Explicit tenant_id always takes precedence
results = search("products", "widget", tenant_id="other_tenant")

Search Result Cache

Enable caching to reduce backend load for repeated queries:

ICV_SEARCH_CACHE_ENABLED = True
ICV_SEARCH_CACHE_TIMEOUT = 60       # seconds
ICV_SEARCH_CACHE_ALIAS = "default"  # Django cache alias

Cache is automatically invalidated when documents are indexed or removed.

Merchandising

The merchandising layer lets non-technical users control what shoppers see in search results. It is entirely optional and gated behind a single feature flag.

Enabling

ICV_SEARCH_MERCHANDISING_ENABLED = True
ICV_SEARCH_MERCHANDISING_CACHE_TIMEOUT = 300  # seconds

When disabled (the default), merchandised_search() is a thin wrapper around search() that returns a MerchandisedSearchResult with no merchandising metadata.

Rule Types

All merchandising models inherit from MerchandisingRuleBase, which provides query matching, scheduling (starts_at / ends_at), priority ordering, and hit_count tracking.

The Pipeline

merchandised_search() composes all features into a 9-step pipeline:

1. Feature gate     - disabled? delegate to search()
2. Normalise query  - strip, collapse whitespace, lowercase
3. Redirect check   - short-circuit with URL if matched
4. Query rewrite    - replace query, merge filters/sort
5. Search           - call search() with the (possibly rewritten) query
6. Pin insertion    - insert/move pinned documents
7. Boost re-rank    - multiply scores, re-sort
8. Fallback         - zero results? try alternative strategy
9. Banner attach    - attach matching banners to the result

Each step is individually skippable:

from icv_search.services import merchandised_search

result = merchandised_search(
    "products",
    "red shoes",
    tenant_id="acme",
    skip_redirects=True,
    skip_boosts=True,
    limit=20,
)

Full Pipeline Example

result = merchandised_search("products", "trainers", tenant_id="acme")

if result.redirect:
    return HttpResponseRedirect(result.redirect["url"])

print(result.original_query)   # "trainers"
print(result.was_rewritten)    # True if a rewrite rule matched
print(result.is_fallback)      # True if zero-result fallback triggered
print(result.applied_rules)    # Audit trail of every rule that fired

for banner in result.banners:
    print(banner["title"], banner["position"])

for hit in result.hits:
    if hit.get("_pinned"):
        print(f"[{hit.get('_pin_label', 'pinned')}]", hit["id"])
    else:
        print(hit["id"])

Search Suggestions

get_trending_searches() and get_suggested_queries() derive from existing SearchQueryAggregate data; no external service needed:

from icv_search.services import get_trending_searches, get_suggested_queries

trending = get_trending_searches("products", days=1, limit=10)
# [{"query": "iphone", "count": 342}, ...]

suggestions = get_suggested_queries("products", "iph", limit=5)
# [{"query": "iphone", "count": 342}, {"query": "iphone case", "count": 87}, ...]

Admin

All six merchandising models are registered in the Django admin with list display, filters, search, scheduling fieldsets, bulk enable/disable actions, and read-only hit_count tracking.

Response Types

All service functions return normalised dataclasses, insulating your code from engine-specific response shapes.

SearchResult

@dataclass
class SearchResult:
    hits: list[dict]
    query: str
    processing_time_ms: int
    estimated_total_hits: int
    limit: int
    offset: int
    facet_distribution: dict[str, dict[str, int]]
    formatted_hits: list[dict]
    ranking_scores: list[float | None]
    ranking_score_details: list[dict | None]   # populated when show_ranking_score_details=True
    matches_position: list[dict | None]         # populated when show_matches_position=True
    page: int | None                            # page-based pagination only
    hits_per_page: int | None                   # page-based pagination only
    total_hits: int | None                      # exact count; page-based pagination only
    total_pages: int | None                     # page-based pagination only
    raw: dict

    def get_highlighted_hits(self) -> list[dict]: ...
    def get_facet_values(facet_name: str) -> list[dict]: ...
    def get_hit_with_score(index: int) -> tuple[dict, float | None]: ...

TaskResult

Returned by document indexing and deletion operations:

@dataclass
class TaskResult:
    task_uid: str    # Engine-assigned task identifier
    status: str      # e.g. "enqueued", "succeeded"
    detail: str      # Operation type or description
    raw: dict        # Original engine response

IndexStats

@dataclass
class IndexStats:
    document_count: int
    is_indexing: bool
    field_distribution: dict[str, int]
    raw: dict

MerchandisedSearchResult

Extends SearchResult with:

Backends

Meilisearch (default)

Requires a running Meilisearch instance (v1.0+). Uses httpx directly rather than the official SDK, keeping dependencies minimal.

ICV_SEARCH_BACKEND = "icv_search.backends.meilisearch.MeilisearchBackend"
ICV_SEARCH_URL = "http://localhost:7700"
ICV_SEARCH_API_KEY = "your-master-key"

PostgreSQL (zero infrastructure)

Uses Django's built-in django.contrib.postgres.search with tsvector indexing. No external services required. Supports full-text search with ts_rank, Django-native filters and sorts.

Best for projects that want search without running Meilisearch, or as a starting point before upgrading to a dedicated engine.

ICV_SEARCH_BACKEND = "icv_search.backends.postgres.PostgresBackend"
# ICV_SEARCH_URL and ICV_SEARCH_API_KEY are ignored by this backend.

DummyBackend (testing)

An in-memory backend that stores documents in module-level dicts. Supports basic substring search, limit, and offset. No running search engine required.

# tests/settings.py
ICV_SEARCH_BACKEND = "icv_search.backends.dummy.DummyBackend"
ICV_SEARCH_ASYNC_INDEXING = False  # Keep tests synchronous

Writing a Custom Backend

Subclass BaseSearchBackend and implement the abstract interface:

from icv_search.backends.base import BaseSearchBackend

class MyBackend(BaseSearchBackend):

    def __init__(self, url: str, api_key: str, timeout: int = 30, **kwargs):
        super().__init__(url=url, api_key=api_key, timeout=timeout, **kwargs)

    def create_index(self, uid: str, primary_key: str = "id") -> dict: ...
    def delete_index(self, uid: str) -> None: ...
    def update_settings(self, uid: str, settings: dict) -> dict: ...
    def get_settings(self, uid: str) -> dict: ...
    def add_documents(self, uid: str, documents: list[dict], primary_key: str = "id") -> dict: ...
    def delete_documents(self, uid: str, document_ids: list[str]) -> dict: ...
    def clear_documents(self, uid: str) -> dict: ...
    def search(self, uid: str, query: str, **params) -> dict: ...
    def get_stats(self, uid: str) -> dict: ...
    def health(self) -> bool: ...

Raise icv_search.exceptions.SearchBackendError on failure so the service layer handles errors consistently.

ICV_SEARCH_BACKEND = "myproject.search_backends.MyBackend"

Management Commands

python manage.py icv_search_setup
python manage.py icv_search_setup --dry-run
python manage.py icv_search_health --verbose
python manage.py icv_search_sync --index products --force
python manage.py icv_search_reindex --index products --model myapp.models.Product --batch-size 500
python manage.py icv_search_clear --index products

SearchIndex records are also auto-created on first use: calling search("products", "shoes") creates the record if it does not exist. icv_search_setup is the recommended way to provision indexes explicitly during deployment.

Celery Tasks

Celery is optional. When not installed, all operations run synchronously. When installed with ICV_SEARCH_ASYNC_INDEXING = True, operations are dispatched as background tasks with exponential backoff (maximum three retries).

from celery.schedules import crontab

CELERY_BEAT_SCHEDULE = {
    "icv-search-sync-all": {
        "task": "icv_search.tasks.sync_all_indexes",
        "schedule": crontab(minute="*/5"),
    },
    "icv-search-refresh-counts": {
        "task": "icv_search.tasks.refresh_document_counts",
        "schedule": crontab(minute=0),
    },
    "icv-search-cleanup-query-logs": {
        "task": "icv_search.tasks.cleanup_search_query_logs",
        "schedule": crontab(hour=3, minute=0),
    },
    "icv-search-cleanup-query-aggregates": {
        "task": "icv_search.tasks.cleanup_search_query_aggregates",
        "schedule": crontab(hour=3, minute=15),
    },
}

Signals

All signals are defined in icv_search.signals.

from django.dispatch import receiver
from icv_search.signals import documents_indexed
from icv_search.models import SearchIndex

@receiver(documents_indexed, sender=SearchIndex)
def on_documents_indexed(sender, instance, count, document_ids, **kwargs):
    print(f"{count} documents indexed in '{instance.name}'")

Testing

Using DummyBackend

# tests/settings.py
ICV_SEARCH_BACKEND = "icv_search.backends.dummy.DummyBackend"
ICV_SEARCH_ASYNC_INDEXING = False  # Synchronous so assertions work immediately

Fixtures and Factories

icv_search.testing provides ready-made fixtures and factories for consuming projects:

# conftest.py
from icv_search.testing.fixtures import search_backend, search_index  # noqa: F401

Factories in icv_search.testing.factories: SearchIndexFactory, IndexSyncLogFactory, SearchQueryAggregateFactory, QueryRedirectFactory, QueryRewriteFactory, SearchPinFactory, BoostRuleFactory, SearchBannerFactory, ZeroResultFallbackFactory.

Asserting Documents

from icv_search.testing.helpers import (
    get_indexed_documents,
    assert_document_indexed,
)

def test_product_indexed(db, search_backend):
    product = ProductFactory()
    assert_document_indexed("products", str(product.pk))

def test_all_products_indexed(db, search_backend):
    ProductFactory.create_batch(5)
    docs = get_indexed_documents("products")
    assert len(docs) == 5

skip_index_update in Factories

Use skip_index_update() in test factories to prevent auto-index noise when creating supporting data:

import factory
from icv_search.auto_index import skip_index_update

class ArticleFactory(factory.django.DjangoModelFactory):
    class Meta:
        model = Article

    @classmethod
    def _create(cls, model_class, *args, **kwargs):
        with skip_index_update():
            return super()._create(model_class, *args, **kwargs)

Multi-Tenancy

Tenant-prefixed index names via a configurable callable. No foreign key to a tenant model: no coupling to any specific tenant implementation.

# myproject/search.py
def get_tenant_prefix(request_or_none) -> str:
    if request_or_none and hasattr(request_or_none, "tenant"):
        return request_or_none.tenant.slug
    return ""

# settings.py
ICV_SEARCH_TENANT_PREFIX_FUNC = "myproject.search.get_tenant_prefix"

engine_uid is computed as:

{ICV_SEARCH_INDEX_PREFIX}{tenant_id}_{name}

"staging_acme_products"   # prefix="staging_", tenant="acme", name="products"
"acme_products"           # no prefix, tenant="acme", name="products"
"products"                # single-tenant

Omit ICV_SEARCH_TENANT_PREFIX_FUNC for single-tenant deployments.

Roadmap

• SQLite FTS5 backend
• MySQL FULLTEXT backend
• Async (httpx.AsyncClient) support for ASGI applications
• Typesense backend
• Search result click-through tracking
• A/B testing for ranking rules
• PostGIS-backed geo search

Licence

MIT