Algolia Search integration for Django

Warnings

• breaking Version 4.0.0 drops support for Python versions older than 3.8 and Django versions older than 4.0. Ensure your project meets these minimum requirements before upgrading.
  Fix: Upgrade Python to 3.8+ and Django to 4.0+. Refer to Django's own upgrade guides for framework-specific changes.
• breaking The `clear_index` method has been removed in favor of `clear_objects` for improved clarity and consistency with the underlying Algolia API client.
  Fix: Replace all calls to `algoliasearch.clear_index(Model)` with `algoliasearch.clear_objects(Model)`.
• breaking The configuration for Algolia in `settings.py` has changed. Instead of `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY` as top-level settings, they are now nested within a single `ALGOLIA` dictionary.
  Fix: Update your `settings.py` to use `ALGOLIA = {'APPLICATION_ID': 'YOUR_APP_ID', 'API_KEY': 'YOUR_API_KEY'}`.
• gotcha When performing searches from the frontend, use the dedicated 'Search-Only API Key' rather than the 'Admin API Key'. The Admin API Key has full write access and should never be exposed client-side.
  Fix: Distinguish between 'API_KEY' (Admin) for backend operations and 'SEARCH_API_KEY' (Search-Only) for frontend search queries.
• gotcha Records exceeding Algolia's size limit (typically 10KB) will cause indexing errors. This often occurs when indexing too many fields or large related objects.
  Fix: Carefully select which fields to index using the `fields` attribute in `AlgoliaIndex`. Consider using `get_extra_attributes` or `get_raw_record` to preprocess and limit the data sent to Algolia, only indexing data relevant for search.
• gotcha Issues can arise with Many-to-Many relationships not updating correctly in the Algolia index, particularly on model saves. Sometimes manual re-indexing is required.
  Fix: Ensure that related objects are correctly handled, potentially by overriding `save_record` or using custom signals to trigger updates to the main model's index entry when M2M relationships change. Manual re-indexing (`python manage.py algolia_reindex`) might be necessary in some cases.

Install

• pip install algoliasearch-django Install latest version

Imports

• algoliasearch

  import algoliasearch_django as algoliasearch

  The official documentation and recent examples consistently use 'import algoliasearch_django as algoliasearch' for the module that exposes `register`.
• AlgoliaIndex

  from algoliasearch_django import AlgoliaIndex

• register (decorator)

  from algoliasearch_django.decorators import register

Quickstart

To get started, first configure your Algolia credentials in your Django `settings.py` under an `ALGOLIA` dictionary. Then, define your Django models. Finally, create an `index.py` file within your app and register your models for indexing using either `algoliasearch.register()` or the `@register` decorator with a subclass of `AlgoliaIndex` to specify index settings and fields. Remember to add `algoliasearch_django` to your `INSTALLED_APPS`.

import os
import django
from django.conf import settings
from django.db import models

# Configure Django settings minimally for standalone execution
if not settings.configured:
    settings.configure(
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'myapp',
            'algoliasearch_django'
        ],
        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
        ALGOLIA={
            'APPLICATION_ID': os.environ.get('ALGOLIA_APPLICATION_ID', 'YOUR_APP_ID'),
            'API_KEY': os.environ.get('ALGOLIA_API_KEY', 'YOUR_API_KEY'),
            'INDEX_PREFIX': 'dev_',
        },
        DEFAULT_AUTO_FIELD='django.db.models.AutoField',
        SECRET_KEY='a-very-secret-key',
        DEBUG=True
    )
django.setup()

# models.py (example in a fictional 'myapp')
class Product(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

    class Meta:
        app_label = 'myapp'

# index.py (example in 'myapp')
from algoliasearch_django import AlgoliaIndex
from algoliasearch_django.decorators import register

@register(Product)
class ProductIndex(AlgoliaIndex):
    fields = ('name', 'description', 'price', 'created_at')
    settings = {'searchableAttributes': ['name', 'description'], 'attributesForFaceting': ['price']}
    # You can customize `get_attribute_name` or `get_extra_attributes` for more complex indexing

# --- Example Usage (after defining models and index, typically run via manage.py) ---

# This part would typically be run via `python manage.py shell` or a management command.
# For demonstration, we simulate creating and saving an object.
# In a real Django app, signals handle auto-indexing on save.

# Create a product (this would automatically index if AUTO_INDEXING is True, which is default)
# from myapp.models import Product
# p1 = Product.objects.create(name="Wireless Headphones", description="High-quality audio experience.", price=199.99)
# p2 = Product.objects.create(name="Bluetooth Speaker", description="Portable and powerful sound.", price=79.99)
# print("Products created and indexed.")

# To manually reindex all: python manage.py algolia_reindex
# To apply settings: python manage.py algolia_applysettings

print("Algolia Django integration configured. To index data, run 'python manage.py algolia_reindex' or save model instances.")