Setting up Algolia for Django

This package lets you easily integrate the Algolia Search API into your Django project. It’s based on the algoliasearch-client-python package.

You might be interested in this sample Django application providing a typeahead.js based autocompletion and Google-like instant search: algoliasearch-django-example.

• Compatible with Python 3.8 or later.
• Supports Django 4.x and 5.x.

Install

1
pip install --upgrade 'algoliasearch-django>=4.0,<5.0'

Setup

In your Django settings, add algoliasearch_django to INSTALLED_APPS and add these two settings:

1
2
3
4
ALGOLIA = {
    'APPLICATION_ID': 'YourApplicationID',
    'API_KEY': 'YourWriteAPIKey'
}

You can also apply these optional settings:

• INDEX_PREFIX: prefix all indices. Use it to separate different applications, like site1_Products and site2_Products.
• INDEX_SUFFIX: suffix all indices. Use it to differentiate development and production environments, like Location_dev and Location_prod.
• AUTO_INDEXING: automatically synchronize the models with Algolia (default to True).
• RAISE_EXCEPTIONS: raise exceptions on network errors instead of logging them (default to settings.DEBUG).

Quick start

Create an index.py inside each application that contains the models you want to index. Inside this file, call algoliasearch.register() for each of the models you want to index:

1
2
3
4
5
6
7
# index.py

import algoliasearch_django as algoliasearch

from .models import YourModel

algoliasearch.register(YourModel)

By default, all the fields of your model will be used. You can configure the index by creating a subclass of AlgoliaIndex and using the register decorator:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# index.py

from algoliasearch_django import AlgoliaIndex
from algoliasearch_django.decorators import register

from .models import YourModel

@register(YourModel)
class YourModelIndex(AlgoliaIndex):
    fields = ('name', 'date')
    geo_field = 'location'
    settings = {'searchableAttributes': ['name']}
    index_name = 'my_index'

Connection errors

Are you getting “Impossible to connect”, “Unable to connect”, or “Unreachable hosts” errors? First, make sure the issue isn’t at your end:

• Ensure you’re using the correct application ID and API key. Find these credentials on your Algolia dashboard.
• Check for recent changes in your code.
• Check the status of your data center provider.

If you’re using Firebase, you can only access Algolia from a paid Firebase tier.

If you can’t solve the problem yourself, contact the Algolia support team and provide them with the following information:

• The name of your framework integration (Django) and its version number
• A code snippet to reproduce the issue
• Error message or stack trace (if applicable)
• The name of the Algolia index that’s causing problems
• The exact UTC time of the event
• If you can’t connect to the Algolia API from your browser, send the output from community.algolia.com/diag/.

• If you can’t connect to the Algolia API from your servers, send the output from the following command (run on any affected server):

  Shell

  Copy

  1
  curl -sL https://algolia.com/downloads/diag.sh > ./diag.sh && sudo ./diag.sh YourApplicationID
  

  Replace YourApplicationID with your Algolia application ID.

Indexing errors

Any “Record at the position XX objectID=XX is too big” errors during indexing are because you’ve exceeded the size limit for records. Reduce the size of your records and try again.