Algolia Search for Django

This package lets you easily integrate the Algolia Search API to 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 auto-completion and Google-like instant search: algoliasearch-django-example

Compatible with Python 2.7, Python 3.2+ and Django 1.7+

Table of Content

Get started

1. Install
2. Setup
3. Quick Start
4. Commands
5. Search
6. Geo-search
7. Tags
8. Options
9. Run Tests

Install

pip install algoliasearch-django

Setup

In your Django settings, add django.contrib.algoliasearch to INSTALLED_APPS and add these two settings:

ALGOLIA = {
    'APPLICATION_ID': 'MyAppID',
    'API_KEY': 'MyApiKey'
}

There are two optional settings:

• INDEX_PREFIX: prefix all indexes. Use it to separate different applications, like site1_Products and site2_Products.
• INDEX_SUFFIX: suffix all indexes. Use it to differenciate development and production environment, like Location_dev and Location_prod.
• AUTO_INDEXING: automatically synchronize the models with Algolia (default to True).

Quick Start

Simply call AlgoliaSearch.register() for each of the models you want to index. A good place to do this is in your application's AppConfig (generally named apps.py). More info in the documentation

from django.apps import AppConfig
from django.contrib import algoliasearch

class YourAppConfig(AppConfig):
    name = 'your_app'

    def ready(self):
        YourModel = self.get_model('your_model')
        algoliasearch.register(YourModel)

And then, don't forget the line below in the __init__.py file of your Django application.

default_app_config = 'your_django_app.apps.YourAppConfig'

By default, all the fields of your model will be used. You can configure the index by creating a subclass of AlgoliaIndex. A good place to do this is in a separate file, like index.py.

from django.contrib.algoliasearch import AlgoliaIndex

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

And then replace algoliasearch.register(YourModel) with algoliasearch.register(YourModel, YourModelIndex).

Commands

• python manage.py algolia_reindex: reindex all the registered models. This command will first send all the record to a temporary index and then moves it.
• python manage.py algolia_applysettings: (re)apply the index settings.
• python manage.py algolia_clearindex: clear the index

Search

We recommend the usage of our JavaScript API Client to perform queries directly from the end-user browser without going through your server.

However, if you want to search from your backend you can use the raw_search(YourModel, 'yourQuery', params) method. It retrieves the raw JSON answer from the API.

from django.contrib.algoliasearch import raw_search

params = { "hitsPerPage": 5 }
raw_search(Contact, "jim", params)

Geo-Search

Use the geo_field attribute to localize your record. geo_field should be a callable that returns a tuple (latitude, longitude).

class Contact(models.model):
    name = models.CharField(max_lenght=20)
    lat = models.FloatField()
    lng = models.FloatField()

    def location(self):
        return (self.lat, self.lng)


class ContactIndex(AlgoliaIndex):
    fields = 'name'
    geo_field = 'location'


algoliasearch.register(Contact, ContactIndex)

Tags

Use the tags attributes to add tags to your record. It can be a field or a callable.

class ArticleIndex(AlgoliaIndex):
    tags = 'category'

At query time, specify { tagFilters: 'tagvalue' } or { tagFilters: ['tagvalue1', 'tagvalue2'] } as search parameters to restrict the result set to specific tags.

Options

Custom objectID

You can choose which field will be used as the objectID . The field should be unique and can be a string or integer. By default, we use the pk field of the model.

class ArticleIndex(AlgoliaIndex):
    custom_objectID = 'post_id'

Custom index name

You can customize the index name. By default, the index name will be the name of the model class.

class ContactIndex(algoliaindex):
    index_name = 'Entreprise'

Index settings

We provide many ways to configure your index allowing you to tune your overall index relevancy. All the configuration is explained on our website.

class ArticleIndex(AlgoliaIndex):
    settings = {
        'attributesToIndex': ['name', 'description', 'url'],
        'customRanking': ['desc(vote_count)', 'asc(name)']
    }

Restrict indexing to a subset of your data

You can add constraints controlling if a record must be indexed or not. should_index should be a callable that returns a boolean.

class Contact(models.model):
    name = models.CharField(max_lenght=20)
    age = models.IntegerField()

    def is_adult(self):
        return (self.age >= 18)

class ContactIndex(AlgoliaIndex):
    should_index = 'is_adult'

Run Tests

To run the tests, first find your Algolia application id and Admin API key (found on the Credentials page).

ALGOLIA_APPLICATION_ID={APPLICATION_ID} ALGOLIA_API_KEY={ADMIN_API_KEY} tox