Published in 12:56 of 02/25/2016 by Bruno Rocha
Bruno Rocha There is more to life than increasing its speed!

Published in 12:56 of 02/25/2016


ESEngine - Elasticsearch Object Doctype Mapper for Python

What is ESEngine

esengine - The Elasticsearch Object Doctype Mapper

PyPI versions downloads Travis CI Coverage Status Code Health

ESEngine is an ODM (Object Doctype Mapper) heavily inspired by MongoEngine, developed with the idea that you have to "Know well your Elastic queries and then write them as Python objects"

You extend the esengine.Document class defining a bunch of fields and meta-attributes and you can use that model to instantiate documents and perform queries on ElasticSearch.

ESEngine is MIT licensed and is open source available at

The documentation is currently only a README full of examples in and also the DocString that can be read using Epydoc in

How it works?

Firstly you need an Elasticsearch Python Client, we recommend using the official one pip install elasticsearch, and then you can define your models using ESEngine objects.

# myproject/
from elasticsearch import Elasticsearch
from esengine import Document, StringField, BooleanField

class Person(Document):
    # meta attributes
    _index = 'myproject'
    _doctype = 'person'

    # default client instance
    _es = Elasticsearch()  # optional, can be passed lazily or can be a callable 

    # field definitions
    name = StringField()
    active = BooleanField()


NOTE: The init() calling will initialize the index/doctype mappings and settings, this part can be omitted and then Elastic Search will try to create this by introspection when the first document is indexed.

With the model definition in a file like myproject/ we can now use the model class Person to Index(insert), edit, delete and of course search documents.

In a Python console:

>>> from myproject.models import Person


>>> user = Person(name=”Bruno”, active=True)
# or simply
>>> user =  Person.create(name=”Bruno”, active=True)


>>> = False
# or simply
>>> user.update(active=False)

Filtering multiple documents

>>> users = Person.filter(active=True)
[ ResultSet generator… a list of active users ]

Bulk update

>>> users.update(active=False)

Performing raw queries (recommended)

>>> query = {“query”: {“match_all”: {}}, “sort”: “name”} 
>>>, size=10)

Querying using Payload helpers (better to create dynamic queries)

>>> from esengine import Payload, Query
>>> query = Query.match_all() 
>>> Payload(model=Person, query=query, sort=”name”).search(size=10)

Deleting documents

>>> user = Person.get(id=123)
>>> user.delete()
# or simply
>>> Person.delete_by_id(123)
# or in bulk
>>> users = Person.filter(active=False)
>>> Person.delete_all(users)
# ou simply
>>> Person.delete_by_query({“query”: …. })

You can find more examples in

Currently ESEngine is being used in 3 of Catholabs production projects and is reaching a nice level of performance and abstraction.

If you use ElasticSearch with Python or want to learn more about it you can follow the readme on github feel free to open issues or collaborating by Pull Requests Pull Requests :)

Let's Search!

  • Publish your Python packages easily using flit in python · 20:19 of 08/22/2017
  • The quality of the python ecosystem in Slides · 21:23 of 06/27/2017
  • Consumindo e Publicando web APIs - PyData São Paulo - 2017 in Slides · 00:58 of 03/29/2017

  • comments powered by Disqus Go Top