==========================
What's new in ElasticUtils
==========================

.. contents::
   :local:


Version 0.6: Released January 17th, 2013
========================================

**API-breaking changes:**

* **S.values_dict no longer always includes id.**

  ``values_dict`` no longer always includes an 'id' field in the
  fields list if you don't specify it.

  Specifying no fields now returns **all** fields::

      S().values_dict()

  Specifying fields now returns only those fields::

      S().values_dict('name', 'number')

* **S.values_list no longer always includes id.**

  ``values_list`` no longer always includes an 'id' field in the
  fields list if you don't specify it.

  Specifying no fields now returns **all** fields::

      S().values_list()

  Specifying fields now returns data for those fields in the order
  the fields are specified::

      S().values_list('name', 'number')

* **Types have changed.**

  This is a big change.

  Up through ElasticUtils v0.5, `S` could take a type and that type was
  a model. This is now completely different.

  In ElasticUtils v0.6 and later, `S` takes a `MappingType`. A
  `MappingType` can be related to a model, but it itself should not be
  a model. This allows us to return search results as a list of
  `MappingType` instances which can do things rather than forcing you
  to do a db hit to get back instances that can do things.

  This is similar to how django-haystack works with the SearchIndex
  class, except ElasticUtils doesn't yet support declarative mapping
  definition.

  See documentation for more details.

* **By default, results are now DefaultMappingType.**

  In ElasticUtils v0.4 and v0.5, if the `S` was untyped and you didn't
  specify either ``values_dict`` or ``values_list``, then the results
  would come back as a list of dicts.

  In ElasticUtils v0.5, if the `S` is untyped and you didn't specify
  either ``values_dict`` or ``values_list``, then the results would
  come back as a list of `DefaultMappingType`.

  See documentation for more details.

* **elasticutils.contrib.django.models.SearchMixin is no more.**

  The `SearchMixin` class is replaced by `DjangoMappingType` which
  relates ElasticSearch mapping types to Django ORM models and
  `Indexable` which is a mixin that adds a bunch of index-related
  infrastructure.

**Changes:**

* Added ``_source`` and ``_id`` to the metadata decorated on the
  search results.

  See documentation for more details.

* Fixed ``elasticutils.contrib.django.es_required_or_50x``.

  It works better now.

* **prefix filter support.**

  ElasticUtils supports prefix filters. You can do this now::

      S().filter(name__prefix='odin')


Version 0.5: Released September 4th, 2012
=========================================

**API-breaking changes:**

None.

**Changes:**

* Added ``demote`` transform: it adds boosting query support allowing
  you to do a negative query which reduces scores for documents that
  match.

* The elasticutils version is now available in ``elasticutils.__version__``
  as well as ``elasticutils._version.__version__``.

* Added ``__in`` support for queries. Doing::

      S().query(foo__in=['a', 'b', 'c'])

  does a terms query now.

* Added `MLT` class which does morelikethis.

* Added API documentation for S, an index, ``order_by`` docs, fixed some
  icky bugs, and generally improved everything at least a little bit.


Version 0.4: Released July 31st, 2012
=====================================

**API-breaking changes:**

* **ElasticUtils no longer requires Django.**

  If you're using Django, you should change your import statements
  from things like::

      from elasticutils import get_es, S, F

  to::

      from elasticutils.contrib.django import get_es, S, F

  Further, Django helper modules like ``cron``, ``tasks``, and
  ``models`` were all moved to ``elasticutils.contrib.django``.

  We moved `ESTestCase` from ``elasticutils.tests`` to
  ``elasticutils.contrib.django.estestcase``

  If you don't use Django, ElasticUtils is easier to use!

* **S no longer requires a type.**

  If you're not using Django, `S` no longer requires a type. If you
  don't specify a type, then ElasticUtils will return results as
  dicts.

* **Values and values_list changed.**

  ``values()`` was renamed to ``values_list()``.

  ``values_list()`` (was ``values()``) now always returns a list of
  tuples even if you only requested a single field. Previously, doing
  something like::

      searcher = S().values_list('id')

  would return something like::

      [1, 2, 3, 4, 5]

  Now it returns::

      [(1,), (2,), (3,), (4,), (5,)]

* **Facet functionality was rewritten.**

  Changed ``.facet()`` to be arg-driven and allow for `filtered` and
  `global_` flags.

  Changed ``.facets()`` to ``.facet_counts()`` to match Django
  Haystack.

  Added ``.facet_raw()`` which allows you to do more complicated
  facets including scripting. This is similar to the original
  ``.facet()`` implementation.


**Changes:**

* Overhauled and cleaned up ElasticUtils tests. Running tests can be done
  with::

      DJANGO_SETTINGS_MODULE=es_settings nosetests

* Default timeout was changed from 1 second to 5 seconds.

* Added ``es`` transform: it allows you to specify the settings with which
  to create an ES when the search is executed.

* Added ``es_builder`` transform: it allows you to specify a function
  that builds an ES which will be executed to create an ES when the
  search is executed.

* Added ``indexes`` transform: it allows you to specify the indexes to
  use for the search.

* Added ``doctypes`` transform: it allows you to specify the doctypes
  to use for the search.

* Added ``explain`` transform: it allows you to set the "explain" flag
  which gives you an explanation of how the score was calculated.

  I also added ``elasticutils.utils.format_elasticutils`` which formats
  the resulting explanation text into something slightly more
  readable. But it's likely this will change in the future.

* Added ``boost`` transform: it allows you to do query-time field
  boosting.

* Added support for ``prefix``. It's the same as ``startswith``, but
  it uses the same word that ElasticSearch uses. At some point, we'll
  remove support for ``startswith``.

* Added support for ``text_phrase`` and ``query_string`` queries.

* Added ``highlight`` transform: generates highlighted fragments of
  content that matched the query.

* Removed requirement for nuggets.

* Continued to improve documentation.


Version 0.3: Released June 1st, 2012
====================================

**Changes:**

* Add documentation for debugging, project details and other things.

* Minor project cleanup to make it easier to maintain and use

* Make ``get_es()`` more useful. It now takes overrides that allow you to
  configure multiple kinds of ES objects for different purposes.
