Client to connect to the Sheldon GraphDB
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This is the basic library to fetch data from or store data to sheldon. This gem is not publicly available. To install it, check out the source, bundle and install the gem manually, like that:

git clone
cd sheldon-client
rake build

Sheldon Communication

As this is a simple REST wrapper, we keep things fairly simple here. If we need a more sophisticated version of this, we should consider moving to ActiveResource or any other REST wrapper.

First of all you might want to check out this small example.

irb > gem 'sheldon-client'
irb > = '' # this is the default host
irb > :movies, title: 'The Matrix'
=> [#<Sheldon::Node 430 (Movie/The Matrix)>] 
irb > _.first.payload['production_year']
=> "1999"

Beside searching, you can use SheldonClient to create edges. Please consult your sheldon manual (aka jayniz) for valid edge types.

irb > matrix = :movies, title: 'The Matrix' ).first
irb > action = :genres, name: 'Action').first
irb > SheldonClient.create_edge from: matrix, to: action, type: 'hasGenre', payload: { weight: 1.0 }
=> true

Please bear in mind, that this client library does little to no validations. So if you get an exception, you probably passed in options that sheldon (or this client for that matter) cannot deal with. Feel free to improve stability if necessary.


There just two basic configuration settings. You can set the sheldon host and you can activate logging. If you omit the :log_file option, sheldon-client will log to stdout.

irb > = 'http://my.sheldon/host'
irb > SheldonClient.log  = true
irb > SheldonClient.log_file = '/var/log/sheldon-slow.log'

Functions and example code

Fetching node

Fetch a single node object from sheldon


  • id - the sheldon id


SheldonClient.node 17007
=> #<Sheldon::Node 17007 (Movie/Tonari no Totoro)>

Fetching edge

Fetches a single edge from shelson


* <tt>id</tt> - The sheldon id of the edge


SheldonClient.edge 5
=> #<Sheldon::Edge 5 (GenreTagging/2->1)>

Checking if an edge exist

Checks if an edge of a certain type exist between two nodes in sheldon


* <tt>sheldon node</tt> - Source node
* <tt>sheldon node</tt> - Target node
* <tt>type</tt> - Edge type


movie =, { title: 'The Matrix'} ).first
genre =, { name: 'Action'} ).first
SheldonClient.edge? movie, genre, 'genre_taggings'
SheldonClient.edge? 416, 190637, 'genre_taggings'
 => #<Sheldon::Edge 6113 (GenreTagging/416->190637)>

Fetching outgoing/ingoing edges from a node

Fetch all the edges of a certain type connected to a given node.


  • node The node that we are going to fetch edges from

  • type The egde type we are interesting in


movie =, { title: '99 Euro*'} ).first
edges = SheldonClient.fetch_edges(movie, 'genre_taggings')

genre =, name: 'Drama').first
edges = SheldonClient.fetch_edges(genre, 'genre_taggings')

Fetching node by facebook id

Fetches an node regardless the node type.


fbid - The facebook id

Examples '1234567' )
  => #<Sheldon::Node 17007 (Movie/Mononoke Hime)>

Creating node

Create a new node at sheldon.


  • options - The payload for the node


Create a new movie node

SheldonClient.create_node(type: :movie, payload: { title: "Full Metal Jacket" })
=> SheldonClient::Node object

SheldonClient.create_node(type: 'users', payload: { username:'Britney Spears', facebook_ids: '542032345 })
=> SheldonClient::Node object

Creating edge

Create an edge between two sheldon nodes.


  • options - the options to create an edge. This must include

    The <tt>to</tt> and <tt>from</tt> option
    accepts a SheldonClient::Node Object or an integer.


Create an edge between a movie and a genre.

matrix = :movies, title: 'The Matrix' ).first
action = :genres, name: 'Action').first
SheldonClient.create_edge {from: matrix, to: action, type: 'genretagging', payload: { weight: 1.0 }
=> true

Updating node

Updates the payload in a node


  • options - The options that is going to be updated in the node include the payload


Update a node

SheldonClient.update_node( 450, {  year: '1999'} )
 => true

SheldonClient.update_node( 456, {  title: 'Air bud'} )
 => true

Deleting Node

Deletes a node from the database


  • id - The node id we want to be deleted from the database


 => true

SheldonClient.delete_node(201) //Non existant node
 => false

Deleting edge

Deletes a edge from the database


* <tt>id</tt> - The edge id we want to be deleted from the database


 => true

SheldonClient.delete_edge(65) //Non existant edge
 => false

Searching for nodes

Search for Sheldon Nodes. This will return an array of SheldonClient::Node Objects or an empty array.


  • type - plural of any known sheldon node type like :movies or :genres

  • options - the search option that will be forwarded to lucene. This depends on the type, see below.

Search Options

Depending on the type of nodes you're searching for, different search options should be provided. Please refer to the sheldon documentation for the most up-to-date version of this. As of today, the following search options are supported.

  • movies - title, production_year

  • genres - name

  • person - name

Sheldon will pass the search options to lucene, so if an option is supported and interpreted as exptected need to be verified by the Sheldon team. See for more information.


Search for a specific movie :movies, { title: 'The Matrix' } :movies, { title: 'Fear and Loathing in Las Vegas', production_year: 1998 }

Search for a specific genre :genres, { name: 'Action' }

And now with wildcards :movies, { title: 'Fist*' }

Fetch all node ids of a certain type

Fetches all the sheldon node ids of a given node type


* <tt>type</tt> - The node type


SheldonClient.get_node_ids_of_type( 'movies' )
=> [1,2,3,4,5,6,7,8, ..... ,9999]

Reindex node

Reindexes a node in sheldon


* <tt>node_id</tt> - The node


SheldonClient.reindex_node( 13 )
=> true

SheldonClient.reindex_node( 37 ) // Non existing node
=> false

Fetch all node types

Fetches all the node types supported by Sheldon


=> ['Movie', 'Actor', 'Genre'....]

Fetch all edge types

Fetches all the egde types supported by Sheldon


=> ['Like', 'Acting'...]

Fetch high score edges

Fetches all the high score edges for a user.
It can fetch all of them, tracked or the untracked


* <tt>id</tt> - The id of the sheldon user node
* <tt>type</tt> - 'tracked' or 'untracked', Optimal parameter. Determins which type of edges that will be returned


SheldonClient.get_highscores 4
=> [ {'id' => 5, 'from' => 6, 'to' => 1, 'payload' => { 'weight' => 5}} ]
SheldonClient.get_highscores 4 'tracked'
=> [ {'id' => 5, 'from' => 6, 'to' => 1, 'payload' => { 'weight' => 5}} ]
SheldonClient.get_highscores 4 'untracked'
=> [ {'id' => 5, 'from' => 6, 'to' => 1, 'payload' => { 'weight' => 5}} ]

SheldonClient.get_highscores_tracked 4
=> [ {'id' => 5, 'from' => 6, 'to' => 1, 'payload' => { 'weight' => 5}} ]

SheldonClient.get_highscores_untracked 4
=> [ {'id' => 5, 'from' => 6, 'to' => 1, 'payload' => { 'weight' => 5}} ]

Fetchrecommendended containers

Fetches all the recommended containers


* <tt>id</tt> - User node id


SheldonClient.get_recommendations 4
=> [
    { id: "50292929"
    , type: "Movie"
      , payload: { title: "Matrix"
                 , production_year: 1999
                 , has_container: "true" }

Contributing to sheldon-client

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


Copyright © 2011 Pontus Lindstrom, Benjamin Krause. See LICENSE.txt for further details.