To make a model searchable, you’ll need to add it into the search index. All pages, images and documents are indexed for you, so you can start searching them right away.

If you have created some extra fields in a subclass of Page or Image, you may want to add these new fields to the search index too so that a user’s search query will match on their content. See Indexing extra fields for info on how to do this.

If the search index is kept separate from the database (when using Elasticsearch for example), you need to keep them both in sync. There are two ways to do this: using the search signal handlers, or calling the update_index command periodically. For best speed and reliability, it’s best to use both if possible.

wagtailsearch provides some signal handlers which bind to the save/delete signals of all indexed models. This would automatically add and delete them from all backends you have registered in WAGTAILSEARCH_BACKENDS. These signal handlers are automatically registered when the wagtail.search app is loaded.

In some cases, you may not want your content to be automatically reindexed and instead rely on the update_index command for indexing. If you need to disable these signal handlers, use one of the following methods:

Wagtail also provides a command for rebuilding the index from scratch.

./manage.pyupdate_index

It is recommended to run this command once a week and at the following times:

whenever any pages have been created through a script (after an import, for example)

whenever any changes have been made to models or search configuration

The search may not return any results while this command is running, so avoid running it at peak times.

Note

The update_index command is also aliased as wagtail_update_index, for use when another installed package (such as Haystack) provides a conflicting update_index command. In this case, the other package’s entry in INSTALLED_APPS should appear above wagtail.search so that its update_index command takes precedence over Wagtail’s.

Fields must be explicitly added to the search_fields property of your Page-derived model, in order for you to be able to search/filter on them. This is done by overriding search_fields to append a list of extra SearchField/FilterField objects to it.

This creates an EventPage model with two fields: description and date. description is indexed as a SearchField and date is indexed as a FilterField

fromwagtail.searchimportindexfromdjango.utilsimporttimezoneclassEventPage(Page):description=models.TextField()date=models.DateField()search_fields=Page.search_fields+[# Inherit search_fields from Pageindex.SearchField('description'),index.FilterField('date'),]# Get future events which contain the string "Christmas" in the title or description>>>EventPage.objects.filter(date__gt=timezone.now()).search("Christmas")

partial_match (boolean) - Setting this to true allows results to be matched on parts of words. For example, this is set on the title field by default, so a page titled HelloWorld! will be found if the user only types Hel into the search box.

boost (int/float) - This allows you to set fields as being more important than others. Setting this to a high number on a field will cause pages with matches in that field to be ranked higher. By default, this is set to 2 on the Page title field and 1 on all other fields.

es_extra (dict) - This field is to allow the developer to set or override any setting on the field in the ElasticSearch mapping. Use this if you want to make use of any ElasticSearch features that are not yet supported in Wagtail.

It’s not possible to filter on any index.FilterFields within index.RelatedFields using the QuerySet API. However, the fields are indexed, so it should be possible to use them by querying Elasticsearch manually.

Filtering on index.RelatedFields with the QuerySet API is planned for a future release of Wagtail.

To do this, inherit from index.Indexed and add some search_fields to the model.

fromwagtail.searchimportindexclassBook(index.Indexed,models.Model):title=models.CharField(max_length=255)genre=models.CharField(max_length=255,choices=GENRE_CHOICES)author=models.ForeignKey(Author,on_delete=models.CASCADE)published_date=models.DateTimeField()search_fields=[index.SearchField('title',partial_match=True,boost=10),index.SearchField('get_genre_display'),index.FilterField('genre'),index.FilterField('author'),index.FilterField('published_date'),]# As this model doesn't have a search method in its QuerySet, we have to call search directly on the backend>>>fromwagtail.search.backendsimportget_search_backend>>>s=get_search_backend()# Run a search for a book by Roald Dahl>>>roald_dahl=Author.objects.get(name="Roald Dahl")>>>s.search("chocolate factory",Book.objects.filter(author=roald_dahl))[<Book:Charlieandthechocolatefactory>]