Manage the reference index¶

Configuration¶

By default, the index will store references between objects managed within the Wagtail admin, specifically:

• all Page types

• Images

• Documents

• models registered as Snippets

• models registered with ModelViewSet

The reference index does not require any further configuration. However there are circumstances where it may be necessary to add or remove models from the index.

from django.apps import AppConfig


class SprocketAppConfig(AppConfig):
    ...
    def ready(self):
        from wagtail.models.reference_index import ReferenceIndex

        from .models import SprocketController

        ReferenceIndex.register_model(SprocketController)

class CentralPage(Page):
    ...
    reference = models.ForeignKey(
        "doc",
        on_delete=models.SET_NULL,
        related_name="page_ref",
    )
    reference.wagtail_reference_index_ignore = True
    ...

Maintenance¶

The index can be rebuilt with the rebuild_references_index management command. This will repopulate the references table and ensure that reference counts are displayed accurately. This should be done if models are manipulated outside of Wagtail, or after an upgrade.

A summary of the index can be shown with the show_references_index management command. This shows the number of objects indexed against each model type, and can be useful to identify which models are being indexed without rebuilding the index itself.

Guarantees and non-guarantees¶

The reference index is a best-effort tracking system, not a strict referential integrity mechanism.

It aims to detect common references created through Wagtail’s built-in models, fields, and blocks, but it does not guarantee that all references between content objects will be detected or enforced.

Using the ReferenceIndex API¶

The wagtail.models.ReferenceIndex model provides a method for querying references between content objects:

ReferenceIndex.get_references_for_object(obj)

This returns a queryset of reference records representing objects that reference the given object.

Enforcing stricter deletion rules¶

The reference index does not automatically prevent content from being deleted. Projects that require stronger guarantees (for example, required StreamField relationships) must enforce those rules in application code.

A common approach is to block deletion of pages that are still referenced elsewhere, based on the reference index results.

from django.core.exceptions import PermissionDenied
from wagtail.hooks import register
from wagtail.models import ReferenceIndex


@register("before_delete_page")
def prevent_deleting_referenced_pages(request, page):
    references = ReferenceIndex.get_references_for_object(page)

    if references.exists():
        raise PermissionDenied(
            "This page is referenced by other content and cannot be deleted."
        )