This document explains how Django-SphinxQL maps a Django model into a Sphinx index.
Sphinx uses a SQL query to retrieve data from a relational database to index it. This means that Django-SphinxQL must know:
- what you want to index (e.g. what data)
- how you want to index it (e.g. type)
In the same spirit of Django, Django-SphinxQL defines an ORM for you to answer those questions. For example:
# indexes.py from sphinxql import fields, indexes from myapp import models class PostIndex(indexes.Index): text = fields.Text('text') # Post has the model field ``text`` date = fields.Date('added_date') summary = fields.Text('summary') # `Post` has a foreign key to a `Blog`, and blog has a name. blog_name = fields.Text('blog__name') class Meta: model = models.Post # the model we are indexing
fields and the
Meta.model identify the “what”; the specific field type,
Text, identifies the “how”. In the following sections the complete API
Formally, when an index is declared, it is registered in the
IndexConfiguratorso Django-SphinxQL configures it in Sphinx.
An index is always composed by two components: a set of
fieldsthat you declare as class attributes and a class
Used to declare Django-SphinxQL related options. An index must always define the
modelof its Meta:
The model of this index. E.g.
model = blog.models.Post.
In case you want to index only particular instances, you can define the class attribute
Optional. The query Sphinx uses to index its data, e.g.
query = models.Post.objects.filter(date__year__gt=2000). If not set, Django-SphinxQL uses
.objects.all(). This is useful if you want to construct indexes for specific sets of instances.
Optional. Defining it automatically enables ranged-queries. This integer defines the number of rows per query retrieved during indexing. It increases the number of queries during indexing, but reduces the amount of data transfer on each query.
In case you want to override Sphinx settings only to this particular index, you can also define the following class attributes:
A dictionary of Sphinx options to override Sphinx settings of
sourcefor this particular index.
See how to use in Defining and overriding settings.
Django-SphinxQL uses fields to identify which attributes from a Django model are indexed:
A field to be added to an
Index. A field is always mapped to a Django queryset, set on its initialization:
my_indexed_text = FieldType('text') # Index.Meta.model contains `text = ...`
You can use both Django’s F expressions or lookup expressions to index related fields or concatenate two fields. For instance, TextField(‘article__text’).
- search fields are indexed for text search, and thus are used for
textual searches with
- attributes are used to filter and order the search results (see
search_order_by()). They cannot be used in textual search.
The following fields are implemented in Django-SphinxQL:
Text: a search field (Sphinx equivalent of no field declaration).
IndexedString: attribute and search field (
String: (non-indexed) attribute for strings (
Date: attribute for dates (
DateTime: attribute for datetimes (
Float: attribute for floats (
Bool: attribute for booleans (
Integer: attribute for integers (
To simply index a Django field, use
Text. If you need an attribute to filter or order your search results, use any of the attributes. Typically
IndexedStringis only needed if you want to use Sphinx without hitting Django’s database (e.g. you redundantly store the data on Sphinx, query Sphinx and use the results of it.
Note that Sphinx
sql_attr_timestampis stored as a unix timestamp, so Django-SphinxQL only supports dates/times since 1970.
- search fields are indexed for text search, and thus are used for textual searches with