What is ESEngine

esengine – The Elasticsearch Object Doctype Mapper

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 http://github.com/catholabs/esengine

The documentation is currently only a README full of examples in http://catholabs.github.io/esengine/ and also the DocString that can be read using Epydoc in http://catholabs.github.io/esengine/docs/

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/models.py
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()

Person.init()

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/models.py 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

Indexing:

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

Updating

>>> user.active = False
>>> user.save()
# 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”} 
>>> Person.search(query=query, 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 https://github.com/catholabs/esengine

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!