ESEngine - Elasticsearch Object Doctype Mapper for Python

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!

Please enable JavaScript to view the comments powered by Disqus.

Disqus