From cfbf7d3e5efcd7bc983d8b1665344f357fa154f4 Mon Sep 17 00:00:00 2001 From: Roel van Dijk Date: Wed, 26 Sep 2012 20:49:46 +0200 Subject: [PATCH] Simplify documentation, move API into Github wiki. --- README.md | 329 +++++++++++++++--------------------------------------- 1 file changed, 90 insertions(+), 239 deletions(-) diff --git a/README.md b/README.md index d9875bc..73131b4 100644 --- a/README.md +++ b/README.md @@ -4,99 +4,52 @@ ## Welcome to Neography Neography is a thin Ruby wrapper to the Neo4j Rest API, for more information: + * [Getting Started with Neo4j Server](http://neo4j.org/community/) * [Neo4j Rest API Reference](http://docs.neo4j.org/chunked/milestone/rest-api.html) If you want to the full power of Neo4j, you will want to use JRuby and the excellent Neo4j.rb gem at https://github.com/andreasronge/neo4j by Andreas Ronge -Complement to Neography are the: - -* [Neo4j Active Record Adapter](https://github.com/yournextleap/activerecord-neo4j-adapter) by Nikhil Lanjewar -* [Neology](https://github.com/lordkada/neology) by Carlo Alberto Degli Atti -* [Neoid](https://github.com/elado/neoid) by Elad Ossadon - -An alternative is the Architect4r Gem at https://github.com/namxam/architect4r by Maximilian Schulz - -### Neography in the Wild - -* [Vouched](http://getvouched.com) -* [Neovigator](http://neovigator.herokuapp.com) fork it at https://github.com/maxdemarzi/neovigator -* [Neoflix](http://neoflix.herokuapp.com) fork it at https://github.com/maxdemarzi/neoflix - -### Getting started with Neography - -* [Getting Started with Ruby and Neo4j](http://maxdemarzi.com/2012/01/04/getting-started-with-ruby-and-neo4j/) -* [Graph visualization with Neo4j](http://maxdemarzi.com/2012/01/11/graph-visualization-and-neo4j/) -* [Neo4j on Heroku](http://maxdemarzi.com/2012/01/13/neo4j-on-heroku-part-one/) - -### Installation +## Installation -```sh - gem install 'neography' -``` +### Gemfile -After that, in your ruby script: +Add `neography` to your Gemfile: ```ruby -require 'rubygems' -require 'neography' -``` - -in order to access the functionality. - - -### Dependencies - -For use: - -``` - os - rake - json - httparty +gem 'neography' ``` -For development: +And run Bundler: +```sh +$ bundle ``` - rspec - net-http-spy -``` - -#### Rails +### Manually: -Just add gem 'neography' to your Gemfile and run bundle install. - -The following tasks will be available to you: +Or install `neography` manually: ```sh -rake neo4j:install # Install Neo4j to the neo4j directory under your project -rake neo4j:install[community,1.6.M03] # Install Neo4j Community edition, version 1.6.M03 -rake neo4j:install[advanced,1.5] # Install Neo4j Advanced edition, version 1.5 -rake neo4j:install[enterprise,1.5] # Install Neo4j Enterprise edition, version 1.5 -rake neo4j:start # Start Neo4j -rake neo4j:stop # Stop Neo4j -rake neo4j:restart # Restart Neo4j -rake neo4j:reset_yes_i_am_sure # Wipe your Neo4j Database +$ gem install 'neography' ``` -Windows users will need to run in a command prompt with Administrative Privileges -in order to install Neo4j as a Service. - -If you are not using Rails, then add: +And require the gem in your Ruby code: ```ruby -require 'neography/tasks' +require 'rubygems' +require 'neography' ``` -to your Rakefile to have access to these tasks. +Read the wiki for information about [dependencies](https://github.com/maxdemarzi/neography/wiki/Dependencies). + +[Rake tasks](https://github.com/maxdemarzi/neography/wiki/Rake-tasks) are available. -`rake neo4j:install` requires `wget` to be installed. It will download and install Neo4j into a neo4j directory in your project regardless of what version you choose. +## Usage -### Documentation +### Configuration and initialization Configure Neography as follows: @@ -125,191 +78,66 @@ Then initialize as follows: @neo = Neography::Rest.new ``` -Or you can override the configured values as follows: +For overriding these default and other initialization methods, see the +[configuration and initialization](https://github.com/maxdemarzi/neography/wiki/Configuration-and-initialization) page in the Wiki. -```ruby -@neo = Neography::Rest.new({ :protocol => 'http://', - :server => 'localhost', - :port => 7474, - :directory => '', - :authentication => 'basic', - :username => 'your username', - :password => 'your password', - :log_file => 'neography.log', - :log_enabled => false, - :max_threads => 20, - :cypher_path => '/cypher', - :gremlin_path => '/ext/GremlinPlugin/graphdb/execute_script' }) -``` -Quick initializer (assumes basic authorization if username is given): +### REST API -```ruby -@neo = Neography::Rest.new("http://username:password@myserver.com:7474/mydirectory") -``` +Neography supports the creation and retrieval of nodes and relationships through the Neo4j interface. +It supports indexes, Gremlin scripts, Cypher queries and batch operations. -Usage: +Some of this functionality is shown here, but all of it is explained in the following Wiki pages: -```ruby -@neo = Neography::Rest.new # Inialize using all default parameters - -@neo.get_root # Get the root node -@neo.create_node # Create an empty node -@neo.create_node("age" => 31, "name" => "Max") # Create a node with some properties -@neo.create_unique_node(index_name, key, unique_value, # Create a unique node - {"age" => 31, "name" => "Max"}) # this needs an existing index - -@neo.get_node(node2) # Get a node and its properties -@neo.delete_node(node2) # Delete an unrelated node -@neo.delete_node!(node2) # Delete a node and all its relationships - -@neo.reset_node_properties(node1, {"age" => 31}) # Reset a node's properties -@neo.set_node_properties(node1, {"weight" => 200}) # Set a node's properties -@neo.get_node_properties(node1) # Get just the node properties -@neo.get_node_properties(node1, ["weight","age"]) # Get some of the node properties -@neo.remove_node_properties(node1) # Remove all properties of a node -@neo.remove_node_properties(node1, "weight") # Remove one property of a node -@neo.remove_node_properties(node1, ["weight","age"]) # Remove multiple properties of a node - -@neo.create_relationship("friends", node1, node2) # Create a relationship between node1 and node2 -@neo.create_unique_relationship(index_name, key, value, # Create a unique relationship between nodes - "friends", new_node1, new_node2) # this needs an existing index - -@neo.get_relationship(rel1) # Get a relationship -@neo.get_node_relationships(node1) # Get all relationships -@neo.get_node_relationships(node1, "in") # Get only incoming relationships -@neo.get_node_relationships(node1, "all", "enemies") # Get all relationships of type enemies -@neo.get_node_relationships(node1, "in", "enemies") # Get only incoming relationships of type enemies -@neo.delete_relationship(rel1) # Delete a relationship - -@neo.reset_relationship_properties(rel1, {"age" => 31}) # Reset a relationship's properties -@neo.set_relationship_properties(rel1, {"weight" => 200}) # Set a relationship's properties -@neo.get_relationship_properties(rel1) # Get just the relationship properties -@neo.get_relationship_properties(rel1, ["since","met"]) # Get some of the relationship properties -@neo.remove_relationship_properties(rel1) # Remove all properties of a relationship -@neo.remove_relationship_properties(rel1, "since") # Remove one property of a relationship -@neo.remove_relationship_properties(rel1, ["since","met"]) # Remove multiple properties of a relationship - -@neo.list_node_indexes # gives names and query templates for all defined indices -@neo.create_node_index(name, type, provider) # creates an index, defaults are "exact" and "lucene" -@neo.create_node_auto_index(type, provider) # creates an auto index, defaults are "exact" and "lucene" -@neo.add_node_to_index(index, key, value, node1) # adds a node to the index with the given key/value pair -@neo.remove_node_from_index(index, key, value, node1) # removes a node from the index with the given key/value pair -@neo.remove_node_from_index(index, key, node1) # removes a node from the index with the given key -@neo.remove_node_from_index(index, node1) # removes a node from the index -@neo.get_node_index(index, key, value) # exact query of the node index with the given key/value pair -@neo.find_node_index(index, key, value) # advanced query of the node index with the given key/value pair -@neo.find_node_index(index, query) # advanced query of the node index with the given query -@neo.get_node_auto_index(key, value) # exact query of the node auto index with the given key/value pair -@neo.find_node_auto_index(query) # advanced query of the node auto index with the given query - -@neo.list_relationship_indexes # gives names and query templates for relationship indices -@neo.create_relationship_index(name, "fulltext", provider) # creates a relationship index with "fulltext" option -@neo.create_relationship_auto_index("fulltext", provider) # creates a relationship auto index with "fulltext" option -@neo.add_relationship_to_index(index, key, value, rel1) # adds a relationship to the index with the given key/value pair -@neo.remove_relationship_from_index(index, key, value, rel1) # removes a relationship from the index with the given key/value pair -@neo.remove_relationship_from_index(index, key, rel1) # removes a relationship from the index with the given key -@neo.remove_relationship_from_index(index, rel1) # removes a relationship from the index -@neo.get_relationship_index(index, key, value) # exact query of the relationship index with the given key/value pair -@neo.find_relationship_index(index, key, value) # advanced query of the relationship index with the given key/value pair -@neo.find_relationship_index(index, query) # advanced query of the relationship index with the given query -@neo.get_relationship_auto_index(key, value) # exact query of the relationship auto index with the given key/value pair -@neo.find_relationship_auto_index(query) # advanced query of the relationship auto index with the given query - -@neo.get_node_auto_index_status # true or false depending on node auto index setting -@neo.get_relationship_auto_index_status # true or false depending on relationship auto index setting -@neo.set_node_auto_index_status(true) # set the node auto index setting to true -@neo.set_relationship_auto_index_status(false) # set the relationship auto index setting to false -@neo.get_node_auto_index_properties # array of currently auto indexed node properties -@neo.get_relationship_auto_index_properties # array of currently auto indexed relationship properties -@neo.add_node_auto_index_property(property) # add to auto indexed node properties -@neo.remove_node_auto_index_property(property) # remove from auto indexed node properties -@neo.add_relationship_auto_index_property(property) # add to auto indexed relationship properties -@neo.remove_relationship_auto_index_property(property) # remove from auto indexed relationship properties - -@neo.execute_script("g.v(0)") # sends a Groovy script (through the Gremlin plugin) -@neo.execute_script("g.v(id)", {:id => 3}) # sends a parameterized Groovy script (optimized for repeated calls) -@neo.execute_query("start n=node(0) return n") # sends a Cypher query (through the Cypher plugin) -@neo.execute_query("start n=node({id}) return n", {:id => 3}) # sends a parameterized Cypher query (optimized for repeated calls) - -@neo.get_path(node1, node2, relationships, depth=4, algorithm="shortestPath") # finds the shortest path between two nodes -@neo.get_paths(node1, node2, relationships, depth=3, algorithm="allPaths") # finds all paths between two nodes -@neo.get_shortest_weighted_path(node1, node2, relationships, # find the shortest path between two nodes - weight_attr='weight', depth=2, # accounting for weight in the relationships - algorithm='dijkstra') # using 'weight' as the attribute - -nodes = @neo.traverse(node1, # the node where the traversal starts - "nodes", # return_type "nodes", "relationships" or "paths" - {"order" => "breadth first", # "breadth first" or "depth first" traversal order - "uniqueness" => "node global", # See Uniqueness in API documentation for options. - "relationships" => [{"type"=> "roommates", # A hash containg a description of the traversal - "direction" => "all"}, # two relationships. - {"type"=> "friends", # - "direction" => "out"}], # - "prune evaluator" => {"language" => "javascript", # A prune evaluator (when to stop traversing) - "body" => "position.endNode().getProperty('age') < 21;"}, - "return filter" => {"language" => "builtin", # "all" or "all but start node" - "name" => "all"}, - "depth" => 4}) - -# "depth" is a short-hand way of specifying a prune evaluator which prunes after a certain depth. -# If not specified a depth of 1 is used and if a "prune evaluator" is specified instead of a depth, no depth limit is set. - -@neo.batch [:get_node, node1], [:get_node, node2] # Gets two nodes in a batch -@neo.batch [:create_node, {"name" => "Max"}], - [:create_node, {"name" => "Marc"}] # Creates two nodes in a batch -@neo.batch [:set_node_property, node1, {"name" => "Tom"}], - [:set_node_property, node2, {"name" => "Jerry"}] # Sets the property of two nodes -@neo.batch [:create_unique_node, index_name, key, value, - {"age" => 33, "name" => "Max"}] # Creates a unique node -@neo.batch [:get_node_relationships, node1, "out", - [:get_node_relationships, node2, "out"] # Get node relationships in a batch -@neo.batch [:get_relationship, rel1], - [:get_relationship, rel2] # Gets two relationships in a batch -@neo.batch [:create_relationship, "friends", - node1, node2, {:since => "high school"}], - [:create_relationship, "friends", - node1, node3, {:since => "college"}] # Creates two relationships in a batch -@neo.batch [:create_unique_relationship, index_name, - key, value, "friends", node1, node2] # Creates a unique relationship -@neo.batch [:get_node_index, index_name, key, value] # Get node index -@neo.batch [:get_relationship_index, index_name, key, value] # Get relationship index +* [Nodes](https://github.com/maxdemarzi/neography/wiki/Nodes) +* [Node properties](https://github.com/maxdemarzi/neography/wiki/Node-properties) +* [Node relationships](https://github.com/maxdemarzi/neography/wiki/Node-relationships) -@neo.batch [:create_node, {"name" => "Max"}], - [:create_node, {"name" => "Marc"}], # Creates two nodes and index them - [:add_node_to_index, "test_node_index", key, value, "{0}"], - [:add_node_to_index, "test_node_index", key, value, "{1}"], - [:create_relationship, "friends", # and create a relationship for those - "{0}", "{1}", {:since => "college"}], # newly created nodes - [:add_relationship_to_index, - "test_relationship_index", key, value, "{4}"] # and index the new relationship - -@neo.batch *[[:create_node, {"name" => "Max"}], - [:create_node, {"name" => "Marc"}]] # Use the Splat (*) with Arrays of Arrays -``` +* [Relationship](https://github.com/maxdemarzi/neography/wiki/Relationships) +* [Relationship properties](https://github.com/maxdemarzi/neography/wiki/Relationship-properties) -See http://docs.neo4j.org/chunked/milestone/rest-api-batch-ops.html for Neo4j Batch operations documentation. +* [Node indexes](https://github.com/maxdemarzi/neography/wiki/Node-indexes) +* [Relationship indexes](https://github.com/maxdemarzi/neography/wiki/Relationship-indexes) +* [Auto indexes](https://github.com/maxdemarzi/neography/wiki/Node-indexes) +* [Scripts and queries](https://github.com/maxdemarzi/neography/wiki/Scripts-and-queries) +* [Paths and traversal](https://github.com/maxdemarzi/neography/wiki/Paths-and-traversal) +* [Batch](https://github.com/maxdemarzi/neography/wiki/Batch) -Please see the specs for more examples. +* [Experimental](https://github.com/maxdemarzi/neography/wiki/Experimental) -Experimental: +Some example usage: ```ruby -nodes = @neo.create_nodes(5) # Create 5 empty nodes -nodes = @neo.create_nodes_threaded(5) # Create 5 empty nodes using threads -nodes = @neo.create_node_nodes([{"age" => 31, "name" => "Max"}, - {"age" => 24, "name" => "Alex"}) # Create two nodes with properties -nodes = @neo.create_node_nodes_threaded([{"age" => 31, "name" => "Max"}, - {"age" => 24, "name" => "Alex"}) # Create two nodes with properties threaded -nodes = @neo.get_nodes([17,86,397,33]) # Get four nodes by their id - -one_set_nodes = @neo.create_nodes(3) -another_node = @neo.create_node("age" => 31, "name" => "Max") -nodes = @neo.get_nodes([one_set_nodes, another_node]) # Get four nodes +# Node creation: +node1 = @neo.create_node("age" => 31, "name" => "Max") +node2 = @neo.create_node("age" => 33, "name" => "Roel") + +# Node properties: +@neo.set_node_properties(node1, {"weight" => 200}) + +# Relationships between nodes: +@neo.create_relationship("coding_buddies", node1, node2) + +# Get node relationships: +@neo.get_node_relationships(node2, "in", "coding_buddies") + +# Use indexes: +@neo.add_node_to_index('people', 'name', 'max', node1) +@neo.get_node_index('people', name', 'max') + +# Cypher queries: +@neo.execute_query("start n=node(0) return n") + +# Batches: +@neo.batch [:create_node, {"name" => "Max"}], + [:create_node, {"name" => "Marc"}] ``` +This is just a small sample of the full API, see the [Wiki documentation](https://github.com/maxdemarzi/neography/wiki) for the full API. + + ### Phase 2 Trying to mimic the Neo4j.rb API. @@ -444,19 +272,42 @@ config.before(:each) do end ``` -### To Do +### Related Neo4j projects + +Complement to Neography are the: + +* [Neo4j Active Record Adapter](https://github.com/yournextleap/activerecord-neo4j-adapter) by Nikhil Lanjewar +* [Neology](https://github.com/lordkada/neology) by Carlo Alberto Degli Atti +* [Neoid](https://github.com/elado/neoid) by Elad Ossadon + +An alternative is the Architect4r Gem at https://github.com/namxam/architect4r by Maximilian Schulz + +### Neography in the Wild + +* [Vouched](http://getvouched.com) +* [Neovigator](http://neovigator.herokuapp.com) fork it at https://github.com/maxdemarzi/neovigator +* [Neoflix](http://neoflix.herokuapp.com) fork it at https://github.com/maxdemarzi/neoflix + +### Getting started with Neography + +* [Getting Started with Ruby and Neo4j](http://maxdemarzi.com/2012/01/04/getting-started-with-ruby-and-neo4j/) +* [Graph visualization with Neo4j](http://maxdemarzi.com/2012/01/11/graph-visualization-and-neo4j/) +* [Neo4j on Heroku](http://maxdemarzi.com/2012/01/13/neo4j-on-heroku-part-one/) + +### To-do * Batch functions * Phase 2 Index functionality -* More Tests +* Phase 2 Unit Tests * More Examples * Mixins ? ### Contributing -[](http://travis-ci.org/maxdemarzi/neography) +[![Build Status](https://secure.travis-ci.org/maxdemarzi/neography.png)](http://travis-ci.org/maxdemarzi/neography) Please create a [new issue](https://github.com/maxdemarzi/neography/issues) if you run into any bugs. + Contribute patches via pull requests. ### Help