How to use the Percolate API with Python

Recently, I’ve been working on migrate a Django project from Solr to Elasticsearch, both of them are great search servers based on Apache Lucene, but Elasticsearch has an interesting feature called Percolate, that’s missing on Solr.

Percolate is the reverse operation of indexing and then searching. Instead of sending docs, indexing them, and then running queries. One sends queries, registers them, and then sends docs and finds out which queries match that doc.

So, here an example of percolation from the Percolate API documentation with Python. See the setup section to known how to setup Elasticsearch and get it running.

First, you’ll want to install pyelasticsearch

$ pip install pyelasticsearch

Open a terminal and type python to use the Python interactive console

>>> from pyelasticsearch import ElasticSearch
>>> es = ElasticSearch('http://localhost:9200')

You need create a new index, named test

>>> es.create_index('test')
{u'acknowledged': True, u'ok': True}

Now, you must specify a query to index. As the _percolator index is also an index, we use the index method to index it, doc_type is the name of the index created before (test) and kuku is our query id

>>> query = {'query': {'term': {'field1': 'value1'}}}
>>> es.index(index='_percolator', doc_type='test', doc=query, id='kuku')
{u'_type': u'test', u'_id': u'kuku', u'ok': True, u'_version': 1, u'_index': u'_percolator'}

Finally to test a percolate request we need call the percolate method with a document

>>> doc = {'doc': {'field1': 'value1'}}
>>> es.percolate(index='test', doc_type='type1', doc=doc)
{u'matches': [u'kuku'], u'ok': True}

We can see that kuku matches with our document.

For more details see the Elasticsearch’s reference API and the documentation of pyelasticsearch.