Backends¶

Database Backend (default)¶

wagtail.search.backends.database

The database search backend searches content in the database using the full text search features of the database backend in use (such as PostgreSQL FTS, SQLite FTS5). This backend is intended to be used for development and also should be good enough to use in production on sites that don’t require any Elasticsearch specific features.

Elasticsearch Backend¶

Elasticsearch versions 5, 6 and 7 are supported. Use the appropriate backend for your version:

• wagtail.search.backends.elasticsearch5 (Elasticsearch 5.x)

• wagtail.search.backends.elasticsearch6 (Elasticsearch 6.x)

• wagtail.search.backends.elasticsearch7 (Elasticsearch 7.x)

Prerequisites are the Elasticsearch service itself and, via pip, the elasticsearch-py package. The major version of the package must match the installed version of Elasticsearch:

pip install "elasticsearch>=5.0.0,<6.0.0"  # for Elasticsearch 5.x

pip install "elasticsearch>=6.4.0,<7.0.0"  # for Elasticsearch 6.x

pip install "elasticsearch>=7.0.0,<8.0.0"  # for Elasticsearch 7.x

The backend is configured in settings:

WAGTAILSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'wagtail.search.backends.elasticsearch5',
        'URLS': ['http://localhost:9200'],
        'INDEX': 'wagtail',
        'TIMEOUT': 5,
        'OPTIONS': {},
        'INDEX_SETTINGS': {},
    }
}

Other than BACKEND, the keys are optional and default to the values shown. Any defined key in OPTIONS is passed directly to the Elasticsearch constructor as case-sensitive keyword argument (for example 'max_retries': 1).

A username and password may be optionally be supplied to the URL field to provide authentication credentials for the Elasticsearch service:

WAGTAILSEARCH_BACKENDS = {
    'default': {
        ...
        'URLS': ['http://username:password@localhost:9200'],
        ...
    }
}

INDEX_SETTINGS is a dictionary used to override the default settings to create the index. The default settings are defined inside the ElasticsearchSearchBackend class in the module wagtail/wagtail/search/backends/elasticsearch7.py. Any new key is added, any existing key, if not a dictionary, is replaced with the new value. Here’s a sample on how to configure the number of shards and setting the Italian LanguageAnalyzer as the default analyzer:

WAGTAILSEARCH_BACKENDS = {
    'default': {
        ...,
        'INDEX_SETTINGS': {
            'settings': {
                'index': {
                    'number_of_shards': 1,
                },
                'analysis': {
                    'analyzer': {
                        'default': {
                            'type': 'italian'
                        }
                    }
                }
            }
        }
    }

If you prefer not to run an Elasticsearch server in development or production, there are many hosted services available, including Bonsai, who offer a free account suitable for testing and development. To use Bonsai:

• Sign up for an account at Bonsai

• Use your Bonsai dashboard to create a Cluster.

• Configure URLS in the Elasticsearch entry in WAGTAILSEARCH_BACKENDS using the Cluster URL from your Bonsai dashboard

• Run ./manage.py update_index

Amazon AWS Elasticsearch¶

The Elasticsearch backend is compatible with Amazon Elasticsearch Service, but requires additional configuration to handle IAM based authentication. This can be done with the requests-aws4auth package along with the following configuration:

from elasticsearch import RequestsHttpConnection
from requests_aws4auth import AWS4Auth

WAGTAILSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'wagtail.search.backends.elasticsearch5',
        'INDEX': 'wagtail',
        'TIMEOUT': 5,
        'HOSTS': [{
            'host': 'YOURCLUSTER.REGION.es.amazonaws.com',
            'port': 443,
            'use_ssl': True,
            'verify_certs': True,
            'http_auth': AWS4Auth('ACCESS_KEY', 'SECRET_KEY', 'REGION', 'es'),
        }],
        'OPTIONS': {
            'connection_class': RequestsHttpConnection,
        },
    }
}