backend-object-mapper

An object mapper for elasticsearch

Contents

• Requirements
• Installation
• Setup
• Docs
  • Definition
  • Property Types
  • Property Types Example
  • Find Entity
    • Search by attribute
    • Geo Query
  • Delete Entity
  • Versioning
    • Get all versions
    • Load a version
  • Using Entity as Property

Requirements

• Python 3.0+
• elasticsearch==5.3.0

Installation

• pip install -r requirements.txt
• python setup.py install
• Elasticsearch instance running. Configuration to be updated in env.sh

Setup

• Update the environment variables for elasticsearch in env.sh and run source ./env.sh

Docs

Definition

Below is the definition of a custom entity

from esorm.entity import StructuredEntity
from esorm.properties import *
from datetime import datetime

class CustomEntity(StructuredEntity):
    name = StringProperty(allowed_values=["custom"])
    uid = UniqueIdProperty()
    date = DateTimeProperty()
    
custom_entity = CustomEntity(name="custom",
                             uid="customuid",
                             date=datetime.utcnow())
                             
# OR

custom_entity = CustomEntity()
custom_entity.set_value('name', 'custom')
custom_entity.set_value('uid', 'customuid')
custom_entity.set_value('date', datetime.utcnow())

# Saving the object
custom_entity.save()

If any of the attributes is not given any value, default values will be assigned to them. For uid, it will generate an internal uid.

Property Types

Following property types are currently supported:

• StringProperty (default: ")
• UniqueIdProperty (default: str()uuid.uuid4())
• IntegerProperty (default: -1)
• FloatProperty (default: float('inf'))
• ArrayProperty (default: [])
• JsonObjectProperty (default: {})
• DateTimeProperty (default: datetime.utcnow())
• GeocoordinateProperty (default: {})

Each property has following options:

• allowed_values
• allowed_values_from_url
• default

Property Type Example

class CustomEntity(StructuredEntity):
    name = StringProperty(allowed_values=["custom"])
    
    # This argument makes a GET request to the specified URL and looks for "allowed_values" key for list of allowed_calues
    address = StringProperty(allowed_values_from_url="http://localhost:5000/")
    
    # The tuple below matches the range of the integers, lowed bound and uppr bound inclusive
    # (20, 30) means all numbers from 20 (inclusive) till 30 (inclusive)
    age = IntegerProperty(allowed_values=[43, (20, 30), 35])
    
    height = FloatProperty(allowed_values=[180.0, (120, 200)])
    
    dob = DateTimeProperty(datetime.utcnow())
    
    # Note: This field always must be named as "coordinates" to be able to query via geo queries
    coordinates = GeocoordinateProperty()
    
    # Note: This field must be named as "uid"
    # This field is mandatory
    uid = UniqueIdProperty()
    
    # Array Property
    phone = ArrayProperty(base_property=StringProperty())

Note: uid is mandatory to define, else ValueError is raised.

Find Entity

Search by attribute

Search by attribute

# Returns a list of matching entities
CustomEntity.entities().get(name="custom")

Geo Queries

# Returns list of matching entities
CustomEntity.entities().get(geo_near=({"lat": 17.45, "lon": 78.56}, 300))

geo_near is a tuple, which takes dict as the first argument, distance in kilometers as the second argument.

Delete an Entity

custom_entity.delete()

Delete doesn't really delete the document, but will disable it for search.

Versioning

Versions of documents are maintained in a separate index located at the config provided in esorm/config

Get all versions

custom_entity.get_all_versions()
# Output
[2,1]

It returns all the version numbers available, greatest number depicting the latest version.

Load a version

# Load a version
custom_entity.load_version(1)

# Save it (a new version is created)
custom_entity.save()

Delete a version

Using Entity as Property

Entities can also be used as properties.

class NewEntity(StructuredEntity):
    uid = UniqueIdProperty()
    entity = CustomEntity()
    entity_list = ArrayProperty(base_property=CustomEntity())
    
new_entity = NewEntity(uid="new", entity=custom_entity, entity_list=[custom_entity])
print(new_entity)

# To get value as JSON (resolves nested JSON)
print(new_entity.get_value_as_json())

Author

Mayank Chutani