263 lines
7.3 KiB
ReStructuredText
263 lines
7.3 KiB
ReStructuredText
.. _ref-searchfield-api:
|
|
|
|
===================
|
|
``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``
|
|
-----------
|
|
|
|
.. attribute:: 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``
|
|
------------
|
|
|
|
.. attribute:: 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``
|
|
-----------
|
|
|
|
.. attribute:: 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``
|
|
-------------------
|
|
|
|
.. attribute:: 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``
|
|
--------------
|
|
|
|
.. attribute:: 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``
|
|
--------
|
|
|
|
.. attribute:: 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``
|
|
----------
|
|
|
|
.. attribute:: 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``
|
|
-----------------
|
|
|
|
.. attribute:: 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``
|
|
----------------
|
|
|
|
.. attribute:: 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__``
|
|
------------
|
|
|
|
.. method:: 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``
|
|
---------------
|
|
|
|
.. method:: SearchField.has_default(self)
|
|
|
|
Returns a boolean of whether this field has a default value.
|
|
|
|
``prepare``
|
|
-----------
|
|
|
|
.. method:: SearchField.prepare(self, obj)
|
|
|
|
Takes data from the provided object and prepares it for storage in the
|
|
index.
|
|
|
|
``prepare_template``
|
|
--------------------
|
|
|
|
.. method:: 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``
|
|
-----------
|
|
|
|
.. method:: 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.
|