Sphinx Configuration¶

Configure Sphinx¶

Note

This part of the documentation requires a minimal understanding of Sphinx.

Running Sphinx requires a configuration file sphinx.conf, normally written by the user, that contains an arbitrary number of sources and indexes, one indexer and one searchd.

Django-SphinxQL provides an API to construct the sphinx.conf in Django: once you run Django with an Index, it automatically generates the sphinx.conf from your code, like Django builds a database when you run migrate.

Note

The sphinx.conf is modified by Django-SphinxQL from your code. It doesn’t need to be added to the version control system.

Equivalently to Django, the sources and indexes of sphinx.conf are configured by an ORM (see Indexes API); indexer and searchd are configured by settings in Django settings.

Django-SphinxQL requires the user to define two settings:

INDEXES['path']: the path of the database (a directory)
INDEXES['sphinx_path']: the path for sphinx-related files (a directory)

For example:

INDEXES = {
    'path': os.path.join(BASE_DIR, '_index'),
    'sphinx_path': BASE_DIR,
}

Note

a) The paths must exist; b) 'path' will contain the Sphinx database. c) ‘sphinx_path’ will contain 3 files:

pid file, searchd.log, and sphinx.conf.

Like Django, Django-SphinxQL already provides a (conservative) default configuration for Sphinx (e.g. it automatically sets Sphinx to assume unicode).

Default settings¶

Django-SphinxQL uses the following default settings:

'index_params': {
    'type': 'plain',
    'charset_type': 'utf-8'
}
'searchd_params': {
    'listen': '9306:mysql41',
    'pid_file': os.path.join(INDEXES['sphinx_path'], 'searchd.pid')
}

Defining and overriding settings¶

Django-SphinxQL applies settings in cascade, overriding previous settings if necessary, in the following order:

first, it uses Django-SphinxQL’s default settings
them, it applies project-wise settings in settings.INDEXES, possibly overriding settings defined in 1.
finally, it applies the settings defined in the Index.Meta, possibly overriding settings in 2.

The project-wise settings use:

settings.INDEXES['searchd_params']
settings.INDEXES['indexer_params']
settings.INDEXES['index_params']
settings.INDEXES['source_params']

Each of them must be a dictionary that maps a Sphinx option (a Python string, e.g. 'charset_table') to a string or a tuple, depending whether the Sphinx option is single-valued or multi-valued.

For example:

INDEXES = {
        ...
        # sets U+00E0 to be considered part of the alphabet (and not be
        # considered a word separator) on all registered indexes.
        'index_params': {
            'charset_table': '0..9, A..Z->a..z, _, a..z, U+00E0'
        }
        # additionally to default, turns off query cache (see Sphinx docs)
        'source_params': {
            'sql_query_pre': ('SET SESSION query_cache_type=OFF',)
        }
        ...
}

You can also override settings of source and index only for a particular index by defining source_params and index_params.

Note

The options must be valid Sphinx options as defined in Sphinx documentation. Django-SphinxQL warns you if some option is not correct or is not valid.

'index_params' and 'source_params' are used on every index configured; 'indexer_params' and 'searchd_params' are used in the indexer and searchd of sphinx.conf.

Configuration references (internal)¶

Warning

This part of the documentation is for internal use and subject to change.

Index configurator¶

class configurators.IndexConfigurator¶

This class is declared only once in Django-Sphinxql, and is responsible for mapping your indexes into a sphinx sphinx.conf.

This class has one entry point, register(), called automatically when Index is defined.

register(index)¶

Registers an Index in the configuration.

This is the entry point of this class to configure a new Index. A declaration of an Index automatically calls this method to register itself.

This method builds the source configuration and index configuration for the index and outputs the updated sphinx.conf to INDEXES['sphinx_path'].

On registering an index, register() gathers settings from three places:

Django settings;
Field of the index;
Meta of the index.

From django.settings:

INDEXES['path']: the directory where the database is created.
INDEXES['sphinx_path']: the directory for sphinx-related files.
INDEXES['indexer_params']: a dictionary with additional parameters for the IndexerConfiguration.
INDEXES['searchd_params']: a dictionary with additional parameters for the SearchdConfiguration.
INDEXES['source_params']: a dictionary with additional parameters for the SourceConfiguration.
INDEXES['index_params']: a dictionary with additional parameters for the IndexConfiguration.

The set of available parameters can be found in Sphinx documentation.

From each field, the configurator uses its type and model_attr; from the Meta, it uses:

model: the Django model the index is respective to.
query: the Django query the index is populated from.
range_step: the step for ranged queries (see Sphinx docs)

source configuration¶

class sphinxql.configuration.configurations.SourceConfiguration(params)¶

A class that can represent itself as an source of sphinx.conf.

It contains the parameters of the source. The argument of this class must be a dictionary mapping parameters to values.

This class always validates the parameters, raising an ImproperlyConfigured if any is wrong. The valid parameters are documented in Sphinx source configuration options.

It has one public method:

format_output()¶: Returns a string with the parameters formatted according to the sphinx.conf syntax.

index configuration¶

class sphinxql.configuration.configurations.IndexConfiguration(params)¶

A class that can represent itself as an index of sphinx.conf.

It contains the parameters of the index. The argument of this class must be a dictionary mapping parameters to values.

This class always validates the parameters, raising an ImproperlyConfigured if any is wrong. The valid parameters are documented in Sphinx index configuration options.

It has one public method:

format_output()¶: Returns a string with the parameters formatted according to the sphinx.conf syntax.

indexer configuration¶

class sphinxql.configuration.configurations.IndexerConfiguration(params)¶

A class that can represent itself as an indexer of sphinx.conf.

It contains the parameters of the indexer. The argument of this class must be a dictionary mapping parameters to values.

This class always validates the parameters, raising an ImproperlyConfigured if any is wrong. The valid parameters are documented in Sphinx indexer configuration options.

It has one public method:

format_output()¶: Returns a string with the parameters formatted according to the sphinx.conf syntax.

searchd configuration¶

class sphinxql.configuration.configurations.SearchdConfiguration(params)¶

A class that can represent itself as the searchd of sphinx.conf.

It contains the parameters of the searchd. The argument of this class must be a dictionary mapping parameters to values.

This class always validates the parameters, raising an ImproperlyConfigured if any is wrong. The valid parameters are documented in Sphinx searchd configuration options.

It has one public method:

format_output()¶: Returns a string with the parameters formatted according to the sphinx.conf syntax.