SearchField API

class SearchField

The SearchField and its subclasses provides a way to declare what data you’re interested in indexing. They are used with SearchIndexes, much like forms.*Field are used within forms or models.*Field within models.

They provide both the means for storing data in the index, as well as preparing the data before it’s placed in the index. Haystack uses all fields from all SearchIndex classes to determine what the engine’s index schema ought to look like.

In practice, you’ll likely never actually use the base SearchField, as the subclasses are much better at handling real data.

Subclasses

Included with Haystack are the following field types:

• BooleanField

• CharField

• DateField

• DateTimeField

• DecimalField

• EdgeNgramField

• FloatField

• IntegerField

• LocationField

• MultiValueField

• NgramField

And equivalent faceted versions:

• FacetBooleanField

• FacetCharField

• FacetDateField

• FacetDateTimeField

• FacetDecimalField

• FacetFloatField

• FacetIntegerField

• FacetMultiValueField

Note

There is no faceted variant of the n-gram fields. Because of how the engine generates n-grams, faceting on these field types (NgramField & EdgeNgram) would make very little sense.

Usage

While SearchField objects can be used on their own, they’re generally used within a SearchIndex. You use them in a declarative manner, just like fields in django.forms.Form or django.db.models.Model objects. For example:

from haystack import indexes
from myapp.models import Note


class NoteIndex(indexes.SearchIndex, indexes.Indexable):
    text = indexes.CharField(document=True, use_template=True)
    author = indexes.CharField(model_attr='user')
    pub_date = indexes.DateTimeField(model_attr='pub_date')

    def get_model(self):
        return Note

This will hook up those fields with the index and, when updating a Model object, pull the relevant data out and prepare it for storage in the index.

Field Options

default

SearchField.default

Provides a means for specifying a fallback value in the event that no data is found for the field. Can be either a value or a callable.

document

SearchField.document

A boolean flag that indicates which of the fields in the SearchIndex ought to be the primary field for searching within. Default is False.

Note

Only one field can be marked as the document=True field, so you should standardize this name and the format of the field between all of your SearchIndex classes.

indexed

SearchField.indexed

A boolean flag for indicating whether or not the data from this field will be searchable within the index. Default is True.

The companion of this option is stored.

index_fieldname

SearchField.index_fieldname

The index_fieldname option allows you to force the name of the field in the index. This does not change how Haystack refers to the field. This is useful when using Solr’s dynamic attributes or when integrating with other external software.

Default is variable name of the field within the SearchIndex.

model_attr

SearchField.model_attr

The model_attr option is a shortcut for preparing data. Rather than having to manually fetch data out of a Model, model_attr allows you to specify a string that will automatically pull data out for you. For example:

# Automatically looks within the model and populates the field with
# the ``last_name`` attribute.
author = CharField(model_attr='last_name')

It also handles callables:

# On a ``User`` object, pulls the full name as pieced together by the
# ``get_full_name`` method.
author = CharField(model_attr='get_full_name')

And can look through relations:

# Pulls the ``bio`` field from a ``UserProfile`` object that has a
# ``OneToOneField`` relationship to a ``User`` object.
biography = CharField(model_attr='user__profile__bio')

null

SearchField.null

A boolean flag for indicating whether or not it’s permissible for the field not to contain any data. Default is False.

Note

Unlike Django’s database layer, which injects a NULL into the database when a field is marked nullable, null=True will actually exclude that field from being included with the document. This is more efficient for the search engine to deal with.

stored

SearchField.stored

A boolean flag for indicating whether or not the data from this field will be stored within the index. Default is True.

This is useful for pulling data out of the index along with the search result in order to save on hits to the database.

The companion of this option is indexed.

template_name

SearchField.template_name

Allows you to override the name of the template to use when preparing data. By default, the data templates for fields are located within your TEMPLATE_DIRS under a path like search/indexes/{app_label}/{model_name}_{field_name}.txt. This option lets you override that path (though still within TEMPLATE_DIRS).

Example:

bio = CharField(use_template=True, template_name='myapp/data/bio.txt')

You can also provide a list of templates, as loader.select_template is used under the hood.

Example:

bio = CharField(use_template=True, template_name=['myapp/data/bio.txt', 'myapp/bio.txt', 'bio.txt'])

use_template

SearchField.use_template

A boolean flag for indicating whether or not a field should prepare its data via a data template or not. Default is False.

Data templates are extremely useful, as they let you easily tie together different parts of the Model (and potentially related models). This leads to better search results with very little effort.

Method Reference

__init__

SearchField.__init__(self, model_attr=None, use_template=False, template_name=None, document=False, indexed=True, stored=True, faceted=False, default=NOT_PROVIDED, null=False, index_fieldname=None, facet_class=None, boost=1.0, weight=None)

Instantiates a fresh SearchField instance.

has_default

SearchField.has_default(self)

Returns a boolean of whether this field has a default value.

prepare

SearchField.prepare(self, obj)

Takes data from the provided object and prepares it for storage in the index.

prepare_template

SearchField.prepare_template(self, obj)

Flattens an object for indexing.

This loads a template (search/indexes/{app_label}/{model_name}_{field_name}.txt) and returns the result of rendering that template. object will be in its context.

convert

SearchField.convert(self, value)

Handles conversion between the data found and the type of the field.

Extending classes should override this method and provide correct data coercion.