Elasticbone
NOTE: This project is still in development, and not production ready. Though hopefully soon it will be.
Elasticsearch is an awesome document store, with a nice rest api. Backbone is an awesome MVC framework, where the model are defined to interact with a rest api. Elasticbone is an extension making it easy for Backbone models to be connected to Elasticsearch documents.
Elasticbone is (should be) usable in both a browser, or node.js server.
To install
npm install elasticbone
Examples
The easiest way to describe elasticbone is to give a few examples based on creating a blog.
Elasticbone = require 'elasticbone'
class User extends Elasticbone.ElasticModel
class Post extends Elasticbone.ElasticModel
class Posts extends Elasticbone.ElasticCollection
model: Post
Elasticmodels and elasticcollections reference an elasticsearch server, index and type.
The default type is the name of the model, in the case of a collection there is no default type.
class User extends Elasticbone.ElasticModel
server: 'localhost:9000'
index: 'blog'
class Post extends Elasticbone.ElasticModel
server: 'localhost:9000'
index: 'blog'
class Posts extends Elasticbone.ElasticCollection
server: 'localhost:9000'
index: 'blog'
type: 'Post'
model: Post
Relationships
Elasticbone also lets you define relationships between backbone models and elasticsearch documents.
To relate models together the has
function (inspired by rails) is used, and options are passed to it.
The basic structure is has 'attribute', Model, {options}
By default the relationship will be treated as a subdocument, e.g.
Given a Post
document in elasticsearch looks like:
{
tags: [{name: 'foo'}, {name: 'bar'}]
}
This relationships would be defined using elasticbone as such,
class Tag extends Backbone.Model
class Tags extends Backbone.Collection
class Post extends Elasticbone.ElasticModel
...
@has 'tags', Tags
NOTE: Tag is not an ElasticModel as it is not a document in Elasticsearch.
has seperate ElasticModel relationship
class Posts extends Elasticbone.ElasticCollection
fetch_query: -> {"query":{"field": {"author":"\"#{this.get('user').name}\""}}}
class User extends Elasticbone.ElasticModel
...
@has 'posts', Posts, method: 'fetch'
user = new User(id: 1)
$.when(user.fetch()).done( (user) -> user.get('posts'))
Since fetching the posts
is expencive Elasticbone will delay it until a get
is called to retreive them.
This uses jquery promises, so that you can register when a callback is fired.
When user.get('posts')
a promise is returned for the posts that are fetched out of elasticsearch using the
fetch_query
. This query returns all posts where the field author
is exactly the users name.
Note: Circular has
A problem occurs when a model wants to have reverse relations, e.g. a user has posts, and a post has a user.
As javascript will execute in order THIS CODE WILL NOT WORK, because when User references posts it will not exist yet.
class User extends Elasticbone.ElasticModel
@has 'posts', Posts
class Posts extends Elasticbone.ElasticCollection
@has 'author', User
Instead you can use has
after the classes declaration
class User extends Elasticbone.ElasticModel
class Posts extends Elasticbone.ElasticCollection
@has 'author', User
User.has 'posts', Posts
GeoRegion & GeoJSON
A supported feature of elasticsearch is its GeoJSON querying with GeoQuery.find_intersecting
class Photo extends Elasticbone.ElasticModel
...
@has 'location', Elasticbone.GeoShape
class Photos extends Elasticbone.ElasticCollection
model: Photo
class GeoRegion extends Elasticbone.ElasticModel
...
@has 'geo_shape', Elasticbone.GeoShape
class GeoRegions extends Elasticbone.ElasticCollection
model: GeoRegion
Something like this will (should) work
#Box around new zealand
gr = new GeoRegion({'geo_shape' : { "type": "Polygon", "coordinates": [ [ [ 166.0, -47.6 ], [166.0, -34.3 ], [179.1, -34.3], [179.1, -47.6] ] ] } }, {parse: true})
#Search for all Photos in New Zealand
$.when(gr.get('geo_shape'))
.then((gs) -> GeoQuery.find_intersecting(gs, Photos, 'location'))
.done((photos) -> console.log "Photos from New Zealand", photos)
Development
Installation: npm inst Testing: npm test
Contribution: Welcome
Production release
Aimed support for
- has_one parse and fetch queries
- has_many parse and fetch queries
- Geographic Queries