.. _ref-searchfield-api: =================== ``SearchField`` API =================== .. class:: SearchField The ``SearchField`` and it's 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`` * ``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.indexes import * class NoteIndex(SearchIndex): text = CharField(document=True, use_template=True) author = CharField(model_attr='user') pub_date = DateTimeField(model_attr='pub_date') 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 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 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.