blueprints library

Joshua Shinavier edited this page Jul 11, 2016 · 18 revisions

The blueprints: library is an extension for interfacing with the Blueprints API and its Property Graph data model.

Note that there is another scripting language, Gremlin, which was heavily influenced by Ripple and is designed especially for Property Graphs. Gremlin is tightly coupled with the Java environment and makes it easy to manipulate and traverse Property Graphs at the command line.

This extension allows you to make calls to Gremlin (using the system:script primitive... see the system library) in order to create graphs and select vertices and edges as starting points, while using Ripple for the actual graph traversal. If you're working at the lower levels of the API, you can instantiate Blueprints Graphs directly, grab vertices and/or edges, and wrap them in VertexValue or EdgeValue objects, respectively. After you have a reference to a Blueprints vertex or edge, you can traverse the graph using head and tail, look up edge labels and vertex/edge ids with label and id, respectively, and find properties and values using key/value predicates (see the graph library).

In order to use the Blueprints extension, you can either build Ripple Java from source (see Running Ripple) and execute the ripple-blueprints.sh script in the ripple-blueprints subdirectory, or import the extension into another Maven-based project by adding the following to your Maven POM:

        <repository>
            <id>fortytwo</id>
            <name>fortytwo.net Maven repository</name>
            <url>http://fortytwo.net/maven2</url>
        </repository>

        ...

        <dependency>
            <groupId>net.fortytwo.ripple</groupId>
            <artifactId>ripple-blueprints</artifactId>
            <version>1.4</version>
        </dependency>

You should make sure that your net.fortytwo.ripple.model.Library provider-configuration file matches the file provided with the extension source code. Specifically, it must contain the line net.fortytwo.ripple.libs.blueprints.BlueprintsLibrary.

head

This primitive finds the head of a Blueprints edge, i.e. the vertex to which the edge is incoming. It expects one argument, an edge, at the top of the stack. It pops the edge from the stack, then pushes the unique head vertex of the edge.

The inverse of head (expressed as head~ or head inverse.) finds the incoming edges of a vertex. It pops a vertex off of the stack and pushes each edge which is incoming to that vertex.

Example:

1)  "g = TinkerGraphFactory.createTinkerGraph(); g.v(1)" "gremlin" script. = v

  [1]  [vertex 1]

2) v. tail~. head.                                                           

  [1]  [vertex 2]
  [2]  [vertex 3]
  [3]  [vertex 4]

3)  @list v1 e v2 name-label-name: v1 "name". e label. v2 "name". 3 ary.    
4)  v. dup. tail~. dup. head.

  [1]  [vertex 1] [edge 7] [vertex 2]
  [2]  [vertex 1] [edge 9] [vertex 3]
  [3]  [vertex 1] [edge 8] [vertex 4]

5)  v. dup. tail~. dup. head. :name-label-name.

  [1]  "marko" "knows" "vadas"
  [2]  "marko" "created" "lop"
  [3]  "marko" "knows" "josh"

id

This primitive finds the unique id of a Blueprints vertex or edge. It expects one argument, a vertex or edge, at the top of the stack. It pops the vertex or edge from the stack, then pushes its id. Since Blueprints supports any class of objects as ids, these are mapped to native Ripple values on a class-by-class basis. These classes are specifically mapped:

  • java.lang.String maps to plain literals
  • java.lang.Double and java.lang.Float map to xsd:double -typed numeric values
  • java.lang.Integer maps to xsd:integer -typed numeric values
  • java.lang.Long maps to xsd:long -typed numeric values
  • java.lang.Boolean maps to xsd:boolean -typed literals

All other classes are wrapped as plain literals, where the toString() representation of the id becomes the label of the literal.

Examples:

1)  "g = TinkerGraphFactory.createTinkerGraph(); g.v(1)" "gremlin" script. = v

  [1]  [vertex 1]

2)  v. id.

  [1]  "1"

3)  v. tail~. dup. id.

  [1]  [edge 7] "7"
  [2]  [edge 9] "9"
  [3]  [edge 8] "8"

4)  v. tail~. head. dup. id.

  [1]  [vertex 2] "2"
  [2]  [vertex 3] "3"
  [3]  [vertex 4] "4"

label

This primitive finds the label of a Blueprints edge. It expects one argument, an edge, at the top of the stack. It pops the edge from the stack and finds the unique string that is the edge's label, pushing the label to the stack.

Example:

1)  "g = TinkerGraphFactory.createTinkerGraph(); g.v(1)" "gremlin" script. = v

  [1]  [vertex 1]

2)  v. tail~. dup. label.

  [1]  [edge 7] "knows"
  [2]  [edge 9] "created"
  [3]  [edge 8] "knows"

tail

This primitive finds the tail of a Blueprints edge, i.e. the vertex from which the edge is outgoing. It expects one argument, an edge, at the top of the stack. It pops the edge from the stack, then pushes the unique tail vertex of the edge.

The inverse of tail (expressed as tail~ or tail inverse.) finds the outgoing edges of a vertex. It pops a vertex off of the stack and pushes each edge which is outgoing from that vertex.

Example:

1)  "g = TinkerGraphFactory.createTinkerGraph(); g.v(1)" "gremlin" script. = v

  [1]  [vertex 1]

2)  v. tail~.

  [1]  [edge 7]
  [2]  [edge 9]
  [3]  [edge 8]