Pacer is all about graph traversals. To traverse the graph with Pacer, you create a Route.
What is a route?
A route is a collection of items (e.g. vertices or edges) that is composable, lazily-loaded and reusable:
- Routes implement Ruby's Enumerable module (with certain exceptions).
- We define routes by composing them with one another.
- When we build a route, no work is done on the graph until you execute it.
- We can execute a route repeatedly.
Alternatively, you can think of a route as a pipe, with a stream of items (e.g. vertices or edges) going into it, and a (possibly different) stream of items coming out of it.
In fact, under the hood, Pacer routes are implemented using Pipes.
For example, consider the following query: Find all flights, with 1 connection, from NYC to LA.
In Pacer, this query will translate into something that looks like the following route:
And the code that creates (and executes) this route will look like this:
g.v(city: 'NYC').out_e.in_v.out_e.in_v(city: 'LA').paths
In the rest of this section, we will go through the different ways you can use routes.
How to use it?
Every traversal needs to start somewhere in the graph.
This starting point can be a vertex, edge, or a collection (i.e. a route) of such elements.
# All vertices
# Some vertices
# Some vertex
# A specific vertex
# All edges
# Some edges
# Some edge
# A specific edge
Get a route of all vertices in the graph
Get a route of all edges in the graph
Get a specific vertex from the graph
Get a specific edge from the graph
Our basic traversals involve moving between vertices and edges that are connected to each other.
# v is a vertex object ...
# Outgoing edges
# Incoming edges
# Both, incoming and outgoing, edges
# e is an edge object ...
# Terminology: out_v --e--> in_v
# The "source" vertex
# The "destination" vertex
# Both, "source" and "destination", vertices
Get the outgoing edges of a vertex (or a vertex route)
Get the incoming edges of a vertex (or a vertex route)
Get both, outgoing and incoming, edges of a vertex (or a vertex route)
Get the source vertex of an edge (or an edge route)
Get the destination vertex of an edge (or an edge route)
Get both vertices of an edge (or an edge route)
All of the basic traversal methods return route objects.
These methods are available for single elements as well as routes, and we can combine them into more interesting traversals.
# Follow outgoing edges to neighbouring vertices
# Follow incoming edges to neighbouring vertices
# Follow two outgoing edges and then one incoming edge