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.