Quick Start

Install JRuby

As of Pacer 1.0.0, JRuby 1.7 is required.
You can get the most recent version of JRuby at RVM.

Install Pacer

The easiest way to get Pacer is

gem install pacer

On some machines you may want to install the gem using jruby -S gem install pacer, in order to allow the irb (the interactive Ruby shell) to pick up the installed gem.

Create and Populate a Graph

The simplest way to get started with Pacer is using the irb. On Windows machines, you may want to run the irb using the command jirb_swing.

Let's create a fairly simple graph data set - Vertices represent airports, and edges represent flights offered from one airport to another.

require 'pacer'

# Create an in-memory TinkerGraph
g = Pacer.tg()

g.transaction do # optional with TinkerGraph

  lax = g.create_vertex({code: 'LAX', city: 'Los Angeles'})
  lga = g.create_vertex({code: 'LGA', city: 'New York'})
  sfo = g.create_vertex({code: 'SFO', city: 'San Francisco'})
  yyz = g.create_vertex({code: 'YYZ', city: 'Toronto'})
  
  lga.add_edges_to(:flies_to, lax, {airline: 'Delta'})
  lga.add_edges_to(:flies_to, yyz, {airline: 'Air Canada'})
  yyz.add_edges_to(:flies_to, lga, {airline: 'Air Canada'})
  lax.add_edges_to(:flies_to, yyz, {airline: 'Delta'})
  lax.add_edges_to(:flies_to, sfo, {airline: 'WestJet'})
  lax.add_edges_to(:flies_to, sfo, {airline: 'American Airlines'})

end

Vertices can contain any number of properties (including 0), specified as a hash.
In our case, vertices represent airports, and we created each vertex with two properties, code and city.
For example:

lax = g.create_vertex({code: 'LAX', city: 'Los Angeles'})

Edges are directed, and must have a label. In addition to that, just like vertices, they can contain an arbitrary hash of properties.
For example, the following line creates an edge from the vertex lga to lax, with the label :flies_to, and a single property airline, whose value is 'Delta'.

lga.add_edges_to(:flies_to, lax, {airline: 'Delta'})

Traverse The Graph

Get all vertices

g.v()

Filter vertices by property (get all vertices whose code is LGA)

g.v({code: 'LGA'})

Access properties

g.v({code: 'LGA'})['city']

Get edges based on vertices.

# Outgoing edges
g.v({code: 'LGA'}).out_e()
# Incoming edges
g.v({code: 'LGA'}).in_e()
# Both
g.v({code: 'LGA'}).both_e()

Example: Get all airlines flying in or out of LaGuardia airport

g.v({code: 'LGA'}).both_e()['airline'].uniq

If you run the command above on the irb, you should see the output:

"Air Canada"        "American Airlines" "Delta"            
Total: 3
#<GraphV -> V-Property(code=="LGA") -> bothE -> Obj(airline) -> decode -> uniq>

We can also get edges from the graph.

g.e()

And filter by property

g.e({airline: 'Delta'})

Get vertices based on edges

# In an edge from x to y, we call x the _out-vertex_, and y the _in-vertex_.

# In-vertices
g.e({airline: 'Delta'}).in_v
# Out-vertices
g.e({airline: 'Delta'}).out_v
# Both
g.e({airline: 'Delta'}).both_v

Example: Get all cities that Delta flies from/to.

g.e({airline: 'Delta'}).both_v['city'].uniq

If you run the command above on the irb, you should see the output:

"Los Angeles" "Toronto"     "New York"   
Total: 3
#<GraphE -> E-Property(airline=="Delta") -> bothV -> Obj(city) -> decode -> uniq>