Add percolator example and improvements

Fixes elastic#861

Author: honzakral

Changelog.rst

@@ -25,6 +25,7 @@ directory. Documentation has been updated to reflect the new API.
 ``7.x``. It does, however, work in the new way which is not fully backwards
 compatible.
 
+* ``Percolator`` field now expects ``Query`` objects as values
 * you can no longer access meta fields on a ``Document`` instance by specifying
   ``._id`` or similar. Instead all access needs to happen via the ``.meta``
   attribute.

elasticsearch_dsl/field.py

@@ -6,10 +6,11 @@
 from datetime import date, datetime
 
 from dateutil import parser, tz
-from six import itervalues, string_types, iteritems
+from six import string_types, iteritems
 from six.moves import map
 
-from .utils import DslBase, ObjectBase, AttrDict, AttrList
+from .query import Q
+from .utils import DslBase, AttrDict, AttrList
 from .exceptions import ValidationException
 
 unicode = type(u'')
@@ -357,6 +358,15 @@ class Completion(Field):
 
 class Percolator(Field):
     name = 'percolator'
+    _coerce = True
+
+    def _deserialize(self, data):
+        return Q(data)
+
+    def _serialize(self, data):
+        if data is None:
+            return None
+        return data.to_dict()
 
 class IntegerRange(Field):
     name = 'integer_range'

examples/README.rst

@@ -28,3 +28,9 @@ A helper function using the `composite aggregation
 <https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-composite-aggregation.html>`_
 to paginate over aggregation results.
 
+``percolate.py``
+----------------
+
+A ``BlogPost`` document with automatic classification using the `percolator
+<https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-percolate-query.html>`_
+functionality.

examples/percolate.py

@@ -0,0 +1,62 @@
+from elasticsearch_dsl import Document, Percolator, Text, Keyword, \
+    connections, Q, Search
+
+connections.create_connection()
+
+class BlogPost(Document):
+    """
+    Blog posts that will be automatically tagged based on percolation queries.
+    """
+    content = Text()
+    tags = Keyword(multi=True)
+
+    class Index:
+        name = 'test-blogpost'
+
+    def add_tags(self):
+        # run a percolation to automatically tag the blog post.
+        s = Search(index='test-percolator')
+        s = s.query('percolate',
+                    field='query',
+                    index=self._get_index(),
+                    document=self.to_dict())
+
+        # collect all the tags from matched percolators
+        for percolator in s:
+            self.tags.extend(percolator.tags)
+
+        # make sure tags are unique
+        self.tags = list(set(self.tags))
+
+    def save(self, **kwargs):
+        self.add_tags()
+        return super(BlogPost, self).save(**kwargs)
+
+class PercolatorDoc(Document):
+    """
+    Document class used for storing the percolation queries.
+    """
+    # relevant fields from BlogPost must be also present here for the queries
+    # to be able to use them. Another option would be to use document
+    # inheritance but save() would have to be reset to normal behavior.
+    content = Text()
+
+    # the percolator query to be run against the doc
+    query = Percolator()
+    # list of tags to append to a document
+    tags = Keyword(multi=True)
+
+    class Index:
+        name = 'test-percolator'
+
+def setup():
+    # create the percolator index if it doesn't exist
+    if not PercolatorDoc._index.exists():
+        PercolatorDoc.init()
+
+    # register a percolation query looking for documents about python
+    PercolatorDoc(
+        _id='python',
+        tags=['programming', 'development', 'python'],
+        query=Q('match', content='python')
+    ).save(refresh=True)

test_elasticsearch_dsl/test_integration/test_examples/percolate.py

@@ -0,0 +1 @@
+../../../examples/percolate.py

test_elasticsearch_dsl/test_integration/test_examples/test_percolate.py

@@ -0,0 +1,13 @@
+from .percolate import setup, BlogPost
+
+def test_post_gets_tagged_automatically(write_client):
+    setup()
+
+    bp = BlogPost(_id=47, content='nothing about snakes here!')
+    bp_py = BlogPost(_id=42, content='something about Python here!')
+
+    bp.save()
+    bp_py.save()
+
+    assert [] == bp.tags
+    assert set(('programming', 'development', 'python')) == set(bp_py.tags)