=====================================
.. Note::
This is a *big* change. We switched from pyes to pyelasticsearch. In
doing that, we changed a handful of signatures, nixed some
functionality that didn't make any sense any more, and cleaned a
bunch of things up.
If this terrifies you, read through these notes carefully and/or
stay with v0.6.
**API-breaking changes:**
* **pyelasticsearch v0.4 or later now required.**
ElasticUtils now requires pyelasticsearch v0.4 or later and its
requirements.
* **elasticutils.PYES_VERSION is removed.**
Since we're not using pyes, we removed `elasticutils.PYES_VERSION`.
* **ElasticUtils no longer supports thrift.**
Pretty sure we did a lousy job of supporting it before---it was all
in the pyes code and we had no tests for it.
* **get_es() signatures have changed.**
* takes urls now instead of hosts
* dump_curl argument is now gone
* default_indexes argument is gone
The arguments correspond with pyelasticsearch `ElasticSearch`
object.
ElasticUtils uses HTTP urls for connecting to Elasticsearch now.
Previously, you'd do::
get_es(hosts=['localhost:9200']) Old way
Now you do::
get_es(urls=['http://localhost:9200']) New way
The dump_curl argument was helpful for debugging, but we don't
really need it anymore. See the :ref:`debugging-chapter` for better
debugging methods.
Will now raise a `DeprecationWarning` if you pass in `hosts`
argument.
* **S searches all indexes and doctypes by default.**
Previously, if you did::
S()
it'd search an index named "default" for doctypes "document". That
was dumb. Now it searches all indexes and all doctypes by default.
* **S.es_builder is gone.**
``es_builder()`` was there to get around problems with pyes' ES
class. The pyelasticsearch `ElasticSearch` class is more
straightforward, so we don't need to do circus shenanigans.
You can probably do what you need to with either the ``es()``
transform or by subclassing `S` and overriding the ``get_es()``
method.
* **MLT arguments changed.**
The `fields` argument in the constructor was renamed to `mlt_fields`
to be in line with Elasticsearch API names.
Will now raise a `DeprecationWarning` if you pass in `fields`
argument.
* **MappingType get_indexes renamed to get_index.**
`MappingType` had a method called `get_indexes`. This is now
`get_index` because it should return a single index name.
* **Added Indexable mixin for indexing bits for MappingTypes.**
* **Django: changed settings.**
Changed ES_HOSTS setting to ES_URLS. This is both a name and a value
change. ES_URLS takes a list of strings each is an http url. You'll
neex to update your settings files from::
ES_HOSTS = ['localhost:9200'] Old way
to::
ES_URLS = ['http://localhost:9200'] New way
ES_DUMP_CURL is gone.
* **Django: removed the statsd code.**
* **Django: ESTestCase was improved, documented and bugs squashed.**
It was improved, documented and bugs were squashed. It's now used by
the test suite.
* **Django: Indexable.index() method no longer has bulk argument.**
The `Indexable.index()` method no longer does bulk indexing. The
way pyes did this was kind of squirrely and caused issues if you
didn't have the order of operations correct.
Now `Indexable.index()` only indexes a single document.
But wait...
* **Django: Indexable now has bulk_index().**
pyes would keep track of all the things you wanted to bulk index
and then at some point push them all. Instead of doing it under the
hood, we added a separate `bulk_index()` method and now you control
how many items get indexed in bulk in one pass.
* **Django: Indexable.refresh_index no longer takes a timeout argument.**
pyelasticsearch `ElasticSearch.refresh` doesn't take a timesleep
argument, so we don't need that anymore.
* **Django: Indexable es argument defaults to Indexable.get_es() now.**
Previously it defaulted to `elasticsearch.contrib.django.get_es()`. Now
it defaults to `Indexable.get_es()` class method making it more flexible.
* **Django: renamed DjangoMappingType to MappingType.**
* **Django: moved MappingType and Indexable.**
They were in ``elasticutils.contrib.django.models`` and are now in
``elasticutils.contrib.django``. Yay for slightly shorter module paths!
* **Django: ditched the cron module and its helpers.**
It's not clear they ever worked (issue 21) and there are no tests.
* **pyes -> pyelasticsearch changes.**
If you called ``.get_es()`` and got a pyes `ES` object and did
things with that (create index, create mappings, delete indexes,
indexing, cluster health, ...), you're going to need to make
some changes.
You can either:
1. rewrite that code to use pyelasticsearch `ElasticSearch`
equivalents, or
2. write and use your own ``get_es()`` function that returns
a pyes `ES` object
Rewriting shouldn't be too hard. The `pyelasticsearch documentation
<https://pyelasticsearch.readthedocs.org/en/latest/>`_ is pretty good
and for most things, there's a 1-to-1 translation.
**Changes:**
* **pyes is no longer a requirement.**
We no longer use pyes so you can remove it from your requirements.
* **S.execute added**
This allows you to explicitly execute a search and get back a
`SearchResults` instance.
See :py:meth:`elasticutils.S.execute` for details.
* **S.all added**
Allows you to get **all** the search results possible rather than
just the first 10 search results which is the default.
You should consider using slices instead which allows you to
specify the maximum number of results to get back.
This is dangerous, so it's been documented with lots of warnings.
See :py:meth:`elasticutils.S.all` for details.
* **Added support for ``match`` and ``match_phrase`` queries.**
Elasticsearch 0.19.9 renamed text query to match query. This adds
support for ``match`` and ``match_phrase``.
See :ref:`queries-queries` for details.
* **Added support for ``wildcard`` and ``terms`` queries.**
See :ref:`queries-queries` for details.
* **Reimplemented filter and query implementation.**
The new implementations allow you to add handling for filters and
queries that ElasticUtils doesn't handle as well as override what
ElasticUtils does.
See :py:class:`elasticutils.S` for details.
* **S.query_raw added**
If :py:meth:`elasticutils.S.query` is getting you down, then you
can skip it and use the Elasticsearch API to create the query clause
of the search by hand with :py:meth:`elasticutils.S.query_raw`.
* **Django: es_required_or_50x handles different exceptions.**
Previously it handled:
* pyes.urllib3.MaxRetryError
* pyes.exceptions.IndexMissingException
* pyes.exceptions.ElasticSearchException
We're not using pyes anymore, so now it handles:
* pyelasticsearch.exceptions.ConnectionError
* pyelasticsearch.exceptions.ElasticHttpError
* pyelasticsearch.exceptions.ElasticHttpNotFoundError
* pyelasticsearch.exceptions.InvalidJsonResponseError
* pyelasticsearch.exceptions.Timeout
You probably don't need to do anything about this, but it's good to
know.
* **Django: celery tasks rewritten.**
The celery tasks were rewritten, docs were updated, and tests were
added so they work now.