EDGE and VERTEX Functions

Graphs consists of nodes or vertexes connected in pairs by relationships or edges. Information about vertexes includes labels such as Person or Employee and vertex properties such as names or age. Information about edges includes the type of an edge, such as "knows", "friend", or "works_at", and properties of an edge, such as a "startDate" or "endDate".

RDF/RDF* graph data is stored in AnzoGraph, which can be queried with SPARQL, however, SPARQL itself does not provide any construct to extract and combine the vertex or edge information as a unit, as might be needed for certain applications. So, AnzoGraph provides two functions, EDGE() and VERTEX(), that help you to do that.

The following provides a description of the two functions, their syntax, and examples of how to use them.

Constructing Edges and Vertexes

Both the EDGE and VERTEX functions return Blob type objects, in JSON format, that represent the edges and vertexes in a graph, along with all their associated attributes and properties. (Both vertexes and edges can have properties.) Following the standard subject-predicate-object representation of triples, the criteria for graph data triples and how various triple data is handled to generate edges and vertexes is the following:

For Vertexes:

The URI in the subject or object position of a triple can be used to construct a vertex.
The rdf:type predicates in graph triples define the label of vertexes.
Triples with non-URI object values are treated as vertex properties. Predicates in those triples are used as the property name and the objects are used to specify the value of properties, for example:
```
<person1> <age> 20
```

The VERTEX function allows you to construct and return a vertex object even if there are no triples in the graph that explicitly specify a vertex as a subject.

For Edges:

Triples where both the subject and object are URIs can be used to construct an edge.
An edge's property name and property value is obtained from the RDF* triple for that edge. Non-URI object values are identified as property values and predicates are treated as the property name. For example:
```
<< <person1> <works_at> <Company1> >> <startDate> "2000-04-27"^^xsd:date .
```

The two functions, VERTEX and EDGE, both construct vertexes and edges returned as Blob type objects from the query in which the functions are called.

You cannot directly pass a vertex or edge (JSON) constructed by the VERTEX or EDGE functions as a parameter or filter in a query, however you can use them as arguments to other functions or expressions within the same query.

VERTEX Function Syntax

The VERTEX function, called from within a SPARQL query, returns labels and properties of nodes or vertexes constructed from triples stored in AnzoGraph.

Prior to loading the data with which you want to use the VERTEX function, AnzoGraph must be configured to register vertex labels as predicates. To configure the system to register vertices as predicates, add the following line to <install_path>/config/settings.conf and then restart AnzoGraph:

auto_predicate=true

For more information about changing settings, see Changing System Settings.

The syntax of the VERTEX function is the following:

azg_blobtype:vertex VERTEX(<uri> variable)

where the "<uri> variable" input argument is the subject or object URI from the graph.

See VERTEX and EDGE Function Examples for a sample data set and some example SPARQL queries that use both VERTEX and EDGE functions.

The VERTEX function takes the vertex URI variable as an argument and returns an azg_blobtype:vertex Blob type object formatted as a JSON string:

<http://anzograph.com/blobtype/vertex>

The JSON output from the VERTEX function is composed of the following :

"id" – Unique identifier for vertex in database
"labels" – Array of vertex labels
"properties" – Properties map

Sample vertex JSON output from the VERTEX function is the following:

{
  "id":4294967405,
  "labels":[
  "Actor",
  "Person"
  ],
  "properties":{
    "born":{
       "type":"typed-literal",
       "datatype":"http://www.w3.org/2001/XMLSchema#int",
       "value":"1956"
    },
    "name":{
       "type":"typed-literal",
       "datatype":"http://www.w3.org/2001/XMLSchema#string",
       "value":"Tom Hanks"
    }
  }
}

EDGE Function Syntax

The EDGE function, called from within a SPARQL query, returns properties and values of relationships or edges constructed from triples stored in AnzoGraph.

See VERTEX and EDGE Function Examples for a sample data set and some example SPARQL queries that use both VERTEX and EDGE functions.

There are two different signatures used to call the EDGE function, both of which provide a way to create the same edge objects. The first syntax method is more straightforward, however, it requires that the AnzoGraph database be in a pristine and unvarying or unaltered state. So, it may return an error in some cases when there are ongoing changes being made to the AnzoGraph database. In that case, you can use the second syntax method, which does not require the same pristine state of the AnzoGraph graph.

Syntax 1:

The syntax and signature of the first EDGE function call is the following:

azg_blobtype:edge EDGE(uri variable,
              edge predicate uri variable,
              uri variable)

This form of EDGE function syntax takes three arguments.

Start vertex URI variable
Edge predicate URI variable
End vertex URI variable

Using this function signature, the EDGE function must appear in the BIND clause within the group graph pattern of a query, delimited with braces ( { } ), immediately following the triple pattern that specifies the subject, predicate, and object variables for the edge. The group graph pattern should not include any clause other than a simple FILTER on the subject, predicate, or object variables for the edge. For example:

SELECT ?acted_in
FROM <Movies>
WHERE {
  ?s a <Actor> .
  {
    ?s ?p ?o . 
    BIND (EDGE(?s,?p,?o) as ?acted_in)
  }
  FILTER(?p = <ACTED_IN>)
}

The EDGE function returns an azg_blobtype:edge Blob type object formatted as a JSON string:

<http://anzograph.com/blobtype/edge>

The JSON output from the EDGE function for both EDGE function signatures is composed of the following :

"start" – ID for starting vertex of edge
"end" – ID for end vertex of edge
"type" – Edge type
"properties" – Properties map

Sample vertex JSON output from the EDGE function is the following:

{
  "id":4294967405,
  "labels":[
  "Actor",
  "Person"
  ],
  "properties":{
    "born":{
       "type":"typed-literal",
       "datatype":"http://www.w3.org/2001/XMLSchema#int",
       "value":"1956"
    },
    "name":{
       "type":"typed-literal",
       "datatype":"http://www.w3.org/2001/XMLSchema#string",
       "value":"Tom Hanks"
    }
  }
}

Syntax 2 (Aggregate):

The syntax and signature of the second aggregate EDGE function call is the following:

azg_blobtype:edge EDGE(uri variable,
              predicate uri variable,
              uri variable,
              property predicate variable,
              property value variable)

The syntax for the aggregate signature of the EDGE function takes five arguments:

Start vertex URI variable
Edge predicate URI variable
End vertex URI variable
Property predicate variable
Property value variable

Also, the query that includes the aggregate EDGE function must group on the first three fields. For example:

select ?s ?p ?o (EDGE(?s,?p,?o,?pp,?pv) as ?edge)
from <Movies>
where {
   ?s ?p ?o .
   optional { << ?s ?p ?o >> ?pp ?pv }
   filter (?p = <ACTED_IN>)
}
group by ?s ?p ?o

The EDGE function returns an azg_blobtype:edge Blob type object formatted as a JSON string:

<http://anzograph.com/blobtype/edge>

Like the EDGE function using the first syntax signature, the aggregate EDGE function syntax is composed of the same elements:

"start" – ID for starting vertex of edge
"end" – ID for end vertex of edge
"type" – Edge type
"properties" – Properties map

VERTEX and EDGE Function Examples

The following statements and the INSERT DATA command creates a GRAPH named Movies that provide a small sample of data you can use to test VERTEX and EDGE functions in SPARQL queries:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
INSERT DATA {
GRAPH <Movies> {
  # triples for "Tom Hanks" vertex
  <TomHanks>  rdf:type <Person>    .
  <TomHanks>  rdf:type <Actor>     .
  <TomHanks>  <name>   "Tom Hanks" .
  <TomHanks>  <born>   1956        .
  # triples for "Forrest Gump" vertex
  <ForrestGump> rdf:type  <Movie>        .
  <ForrestGump> <title>   "Forrest Gump" .
  <ForrestGump> <release> 1994           .
  # edge with properties
  <<<TomHanks> <ACTED_IN> <ForrestGump>>> <roles> "Forrest" .
  # additional triples to force rdf:type uri entries as predicate in the database
  <schema> rdf:type <Schema> .
  <schema> <Schema> "Schema" .
  <schema> <Person> "Person" .
  <schema> <Actor>  "Actor"  .
  <schema> <Movie>  "Movie"  .
  }
}

If auto_predicate=true is set, the triples with <schema> as the subject are not needed.

VERTEX Function

The following example uses the VERTEX function in a SPARQL query to return the vertex for actors defined in the sample Movies graph data described earlier:

select (vertex(?s) as ?actor)
from <Movies>
where {
  ?s a <Actor> .
}

Output from the SPARQL query is the following:

{
  "id":4294967405,
  "labels":[
     "Actor","Person"
  ],
  "properties":{
     "born":{
     "type":"typed-literal","datatype":"http://www.w3.org/2001/XMLSchema#int","value":"1956"},"name":{"type":"typed-literal","datatype":"http://www.w3.org/2001/XMLSchema#string","value":"Tom Hanks"}}}
1 rows

Edge Function (Syntax 1)

The following example uses the EDGE function in a SPARQL query to return node or vertex labels of triples defined in the Movies graph database:

SELECT ?acted_in
FROM <Movies>
WHERE {
  ?s a <Actor> .
  {
    ?s ?p ?o . 
    BIND (EDGE(?s,?p,?o) as ?acted_in)
  }
  FILTER(?p = <ACTED_IN>)
}

Output from the SPARQL query is the following. For readability, the output of the query above is shown on multiple lines.

acted_in
--------
{
  "start":4294967405,
  "end":8589934715,
  "type":"ACTED_IN",
  "properties":{
  "roles":{"type":"typed-literal",
           "datatype":"http://www.w3.org/2001/XMLSchema#string",
           "value":"Forrest"}
  }
}
1 rows

Aggregate EDGE Function (Syntax 2)

The following example creates and returns graph edges with an aggregate query. For this example use, you need to group on subject, predicate, and object in the graph.

select ?s ?p ?o (EDGE(?s,?p,?o,?pp,?pv) as ?edge)
from <Movies>
where {
  ?s ?p ?o .
  optional { << ?s ?p ?o >> ?pp ?pv }
  filter (?p = <ACTED_IN>)
}
group by ?s ?p ?o

Output from the SPARQL query using the aggregate EDGE function syntax is the following. For readability, the output of the query for edge information is shown on multiple lines.

s        | p        | o           | edge
---------+----------+-------------+-----------------------------
TomHanks | ACTED_IN | ForrestGump | {"start":4294967405,
                                     "end":8589934715,
                                     "type":"ACTED_IN",
                                     "properties":{
                                     "roles":{
                                       "type":"typed-literal",
                                       "datatype":"http://www.w3.org/2001/XMLSchema#string",
                                       "value":"Forrest"}
                                       }
                                     }
1 rows