Documents¶

A Document is a mapping class (like a ModelForm), not a Redis row and not a Django model. It says which model fields land in Redis and how related objects are nested.

from redis_search_django import fields
from redis_search_django.documents import Document


class ProductDocument(Document):
    vendor = fields.Object(VendorDocument)
    tags = fields.Nested(TagDocument)

    class Django:
        model = Product
        fields = ["name", "price", "available"]
        auto_index = True
        select_related_fields = ["vendor"]
        prefetch_related_fields = ["tags"]

    class Index:
        storage = "json"          # or "hash"
        search_fields = ["name"]  # optional; default = every TEXT field

class Django¶

class Index¶

app is model._meta.app_label, model is model._meta.model_name, document is the class name lowercased (ProductDocument → productdocument).

Two non-embedded Documents must not share an alias or a prefix.

Field types¶

Declare a field on the Document to override the default mapping.

Default Django → Field¶

None values are omitted from the JSON document so __isnull (ismissing(@field)) works. index_missing is set automatically when the Django field is null=True.

Dates: aware datetimes go through timezone.localtime then UTC epoch. Naive datetimes are treated as UTC. DateField is midnight UTC of that date.

Nested relations¶

Related models are not listed in Django.fields. Declare them with Object (FK / O2O) or Nested (M2M):

class VendorDocument(Document):
    class Django:
        model = Vendor
        fields = ["name"]
        embedded = True


class ProductDocument(Document):
    vendor = fields.Object(VendorDocument)
    category = fields.Object(CategoryDocument, required=False)
    tags = fields.Nested(TagDocument)

• embedded = True means no top-level Redis index and no primary signals. Use those classes only as Object / Nested targets.
• Lookups and facets use Django paths: category__name, tags__name. The compiler maps them to RediSearch aliases (category_name, tags_name).
• A missing optional relation is category__isnull=True (ismissing(@category_pk)). Redis marks INDEXMISSING on the object's pk, not on child TEXT/TAG fields. category__name__isnull=True is rewritten to the same query when name itself is not nullable.

Related-model signals are inferred from Object / Nested unless you set related_models:

Ambiguous graphs (two FKs to the same model) raise at register time. Fix with a dict entry for that model or get_instances_from_related.

On related delete:

• CASCADE on the parent’s FK/O2O → do not upsert the parent; the parent’s post_delete removes the Redis key
• SET_NULL / M2M → reindex the parent without the deleted object

Hooks¶

class ProductDocument(Document):
    ...

    @classmethod
    def get_queryset(cls):
        return super().get_queryset().filter(available=True)

    @classmethod
    def should_index(cls, instance):
        return instance.available

    @classmethod
    def prepare_name(cls, obj):
        return obj.name.upper()

After a blue/green swap, objects.get(pk=) retries once if the process still has the old key prefix cached.