django_mysqlfulltextsearch/README.md

django-mysqlfulltextsearch

django-mysqlfulltextsearch is a simple plug-in for Django that provides access to MySQL's FULLTEXT INDEX feature available in MySQL 5.0 and up.

Although Django supports the "search" lookup in QuerySet filters [http://docs.djangoproject.com/en/dev/ref/models/querysets/#search], the docs specify that you must create the fulltext index yourself. This variant, inspired by code from a blog entry by Andrew Durdin [http://www.mercurytide.co.uk/news/article/django-full-text-search/], includes a return value "relevance," which is the score MySQL awards to each row returned. This is a win for small sites that do not need a heavyweight search solution such as Lucene or Xapian. ("relevance" is supposed to be a configurable dynamic field name, but I haven't provided a reliable path to change it yet.)

Along with the updated API, this code provides for index discovery. If a table has exactly one fulltext index, you can create a SearchManager without declaring any fields at all, and it will auto-discover the index on its own. If you specify a tuple of search fields for which no corresponding index exists, the returned exception will include a list of valid indices.

Standard Usage:

Create the index. For the model "book" in the app "Books":

./manage dbshell
> CREATE FULLTEXT INDEX book_title on books_book (title, summary)

Or via South:

def forwards(self, orm):
    db.execute('CREATE FULLTEXT INDEX book_text_index ON books_book (title, summary)')

Using the index:

from mysqlfulltextsearch import SearchManager
class Books:
    ...
    objects = SearchManager()

books = Book.objects.search('The Metamorphosis', ('title', 'summary')).order_by('-relevance')

> books[0].title
"The Metamorphosis"
> books[0].author
"Franz Kafka"
> books[0].relevance
9.4

If there is only one index for the table, the fields do not need to be specified, the SearchQuerySet object can find it automatically:

from mysqlfulltextsearch import SearchManager
class Books:
    ...
    objects = SearchManager()

books = Book.objects.search('The Metamorphosis').order_by('-relevance')

Tips:

Generating the index is a relatively heavyweight process. When you have a few thousand documents, it might be best to load them first, then generate the index afterward.

To Do:

-- Easy

Make the "relevance" dynamic field name configurable.

-- Moderate

Provide means for matching against BOOLEAN, NATURAL LANGUAGE, and QUERY EXPANSION modes. (Preliminary experiments with this revealed some... interesting... problems with parameter quotation.)

-- Difficult

Provide means for using a SearchManager to access indices on joined tables, for example:

Author.objects.search("The Metamorphosis", "book__title")

-- Insane

Provide for a way to have FULLTEXT search indices specified in a model's Meta class, and have syncdb or south pick up that information and do the right thing with it.