.. _ref-settings:

=================
Haystack Settings
=================

As a way to extend/change the default behavior within Haystack, there are
several settings you can alter within your ``settings.py``. This is a
comprehensive list of the settings Haystack recognizes.


``HAYSTACK_DEFAULT_OPERATOR``
=============================

**Optional**

This setting controls what the default behavior for chaining ``SearchQuerySet``
filters together is.

Valid options are::

    HAYSTACK_DEFAULT_OPERATOR = 'AND'
    HAYSTACK_DEFAULT_OPERATOR = 'OR'

Defaults to ``AND``.


``HAYSTACK_CONNECTIONS``
========================

**Required**

This setting controls which backends should be available. It should be a
dictionary of dictionaries resembling the following (complete) example::

    HAYSTACK_CONNECTIONS = {
        'default': {
            'ENGINE': 'haystack.backends.solr_backend.SolrEngine',
            'URL': 'http://localhost:9001/solr/default',
            'TIMEOUT': 60 * 5,
            'INCLUDE_SPELLING': True,
            'BATCH_SIZE': 100,
        },
        'autocomplete': {
            'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
            'PATH': '/home/search/whoosh_index',
            'STORAGE': 'file',
            'POST_LIMIT': 128 * 1024 * 1024,
            'INCLUDE_SPELLING': True,
            'BATCH_SIZE': 100,
        },
        'slave': {
            'ENGINE': 'xapian_backend.XapianEngine',
            'PATH': '/home/search/xapian_index',
            'INCLUDE_SPELLING': True,
            'BATCH_SIZE': 100,
        },
        'db': {
            'ENGINE': 'haystack.backends.simple_backend.SimpleEngine',
        }
    }

No default for this setting is provided.

The main keys (``default`` & friends) are identifiers for your application.
You can use them any place the API exposes ``using`` as a method or kwarg.

There must always be at least a ``default`` key within this setting.

The ``ENGINE`` option is required for all backends & should point to the
``BaseEngine`` subclass for the backend.

Additionally, each backend may have additional options it requires:

* Solr

  * ``URL`` - The URL to the Solr core.

* Whoosh

  * ``PATH`` - The filesystem path to where the index data is located.

* Xapian

  * ``PATH`` - The filesystem path to where the index data is located.

The following options are optional:

* ``INCLUDE_SPELLING`` - Include spelling suggestions. Default is ``False``
* ``BATCH_SIZE`` - How many records should be updated at once via the management
  commands. Default is ``1000``.
* ``TIMEOUT`` - (Solr-only) How long to wait (in seconds) before the connection
  times out. Default is ``10``.
* ``STORAGE`` - (Whoosh-only) Which storage engine to use. Accepts ``file`` or
  ``ram``. Default is ``file``.
* ``POST_LIMIT`` - (Whoosh-only) How large the file sizes can be. Default is
  ``128 * 1024 * 1024``.
* ``FLAGS`` - (Xapian-only) A list of flags to use when querying the index.


``HAYSTACK_ROUTERS``
====================

**Optional**




``HAYSTACK_EXCLUDED_INDEXES``
=============================

**Optional**




``HAYSTACK_DOCUMENT_FIELD``
===========================

**Optional**




``HAYSTACK_SEARCH_RESULTS_PER_PAGE``
====================================

**Optional**

This setting controls how many results are shown per page when using the
included ``SearchView`` and its subclasses.

An example::

    HAYSTACK_SEARCH_RESULTS_PER_PAGE = 50

Defaults to ``20``.


``HAYSTACK_CUSTOM_HIGHLIGHTER``
===============================

**Optional**

This setting allows you to specify your own custom ``Highlighter``
implementation for use with the ``{% highlight %}`` template tag. It should be
the full path to the class.

An example::

    HAYSTACK_CUSTOM_HIGHLIGHTER = 'myapp.utils.BorkHighlighter'

No default is provided. Haystack automatically falls back to the default
implementation.


``HAYSTACK_ITERATOR_LOAD_PER_QUERY``
====================================

**Optional**

This setting controls the number of results that are pulled at once when
iterating through a ``SearchQuerySet``. If you generally consume large portions
at a time, you can bump this up for better performance.

.. note::

    This is not used in the case of a slice on a ``SearchQuerySet``, which
    already overrides the number of results pulled at once.

An example::

    HAYSTACK_ITERATOR_LOAD_PER_QUERY = 100

The default is 10 results at a time.


``HAYSTACK_LIMIT_TO_REGISTERED_MODELS``
=======================================

**Optional**

This setting allows you to control whether or not Haystack will limit the
search results seen to just the models registered. It should be a boolean.

If your search index is never used for anything other than the models
registered with Haystack, you can turn this off and get a small to moderate
performance boost.

An example::

    HAYSTACK_LIMIT_TO_REGISTERED_MODELS = False

Default is ``True``.


``HAYSTACK_ID_FIELD``
=====================

**Optional**

This setting allows you to control what the unique field name used internally
by Haystack is called. Rarely needed unless your field names collide with
Haystack's defaults.

An example::

    HAYSTACK_ID_FIELD = 'my_id'

Default is ``id``.


``HAYSTACK_DJANGO_CT_FIELD``
============================

**Optional**

This setting allows you to control what the content type field name used
internally by Haystack is called. Rarely needed unless your field names
collide with Haystack's defaults.

An example::

    HAYSTACK_DJANGO_CT_FIELD = 'my_django_ct'

Default is ``django_ct``.


``HAYSTACK_DJANGO_ID_FIELD``
============================

**Optional**

This setting allows you to control what the primary key field name used
internally by Haystack is called. Rarely needed unless your field names
collide with Haystack's defaults.

An example::

    HAYSTACK_DJANGO_ID_FIELD = 'my_django_id'

Default is ``django_id``.
