Returning Edges and Vertexes as JSON Objects

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

Labeled property graphs can be queried with SPARQL. However, SPARQL does not provide a construct to extract and combine the vertex or edge information as a unit, as might be needed for certain applications. AnzoGraph DB provides the EDGE and VERTEX functions for returning edge and vertex data as a JSON object.

Prior to loading the data for which you want to use the VERTEX function, AnzoGraph DB 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 DB:

auto_predicate=true

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

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. Following the standard subject-predicate-object representation of triples, the criteria for how various data is handled to generate edges and vertexes is the following:

Vertexes

  • The URI in the subject or object position of a triple can be used to construct a vertex.
  • The rdf:type predicates 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 the values of properties. For example: 
    <person1> <age> 20

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-star 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 .

You cannot directly pass a vertex or edge 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

The VERTEX function returns labels and properties of nodes or vertexes.

Syntax

VERTEX(?URI_variable) as ?variable

Where ?URI_variable is the variable that represents the targeted subject or object URI.

The VERTEX function returns an <http://anzograph.com/blobtype/vertex> Blob type object formatted as a JSON string with the following elements:

  • id: A unique identifier for the vertex in the database.
  • labels: An array of the labels for the vertex.
  • properties: A list of the properties that are mapped to the vertex.

For example:

{
  "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

The EDGE function returns properties and values of relationships or edges. There are two options for calling 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 database be in a pristine and unvarying or unaltered state. It may return an error in some cases when there are ongoing transactions. In that case, you can use the second method, which does not require the same pristine state of the database.

Syntax 1: No Transactions in Progress

You can use the following syntax to call the EDGE function when the database is at rest—there are no transactions in progress.

BIND(EDGE(?start_vertex, ?edge, ?end_vertex) as ?variable)
Argument Data Type Description
start_vertex URI as a variable The variable that represents the vertex at the start of the edge.
edge URI as a variable The variable that represents the edge or predicate.
end_vertex URI as a variable The variable that represents the vertex at the end of the edge.

Using this syntax, the EDGE function must appear in a BIND clause that immediately follows the triple pattern that specifies the subject, predicate, and object variables for the edge. The WHERE clause should not include any clause other than a simple FILTER on the subject, predicate, or object. 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 <http://anzograph.com/blobtype/edge> Blob type object formatted as a JSON string with the following elements:

  • start: The ID for the starting vertex of the edge.
  • end: The ID for the end vertex of the edge.
  • type: The type of edge.
  • properties: A list of the properties that are mapped to the edge.

For example:

{
  "start":114,
  "end":4294967403,
  "type":"ACTED_IN",
  "properties":{
    "roles":{
    "type":"typed-literal",
    "datatype":"http://www.w3.org/2001/XMLSchema#string",
    "value":"Neo"
    }
  }
}

Syntax 2: Aggregate (Database Updates can be Ongoing)

You can use the following syntax to call the EDGE function when the database is at rest or when transactions are in progress.

EDGE(?start_vertex, ?edge, ?end_vertex, ?edge_property, ?property_value) as ?variable)
...
GROUP BY ?start_vertex ?edge ?end_vertex
Argument Data Type Description
start_vertex URI as a variable The variable that represents the vertex at the start of the edge.
edge URI as a variable The variable that represents the edge or predicate.
end_vertex URI as a variable The variable that represents the vertex at the end of the edge.
edge_property URI as a variable The variable that represents the edge property URI.
property_value variable The variable that represents the value of the property.

The query must include a GROUP BY clause that groups 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 <http://anzograph.com/blobtype/edge> Blob type object formatted as a JSON string with the following elements:

  • start: The ID for the starting vertex of the edge.
  • end: The ID for the end vertex of the edge.
  • type: The type of edge.
  • properties: A list of the properties that are mapped to the edge.

For example:

{
  "start":114,
  "end":4294967403,
  "type":"ACTED_IN",
  "properties":{
    "roles":{
    "type":"typed-literal",
    "datatype":"http://www.w3.org/2001/XMLSchema#string",
    "value":"Neo"
    }
  }
}

Examples

Make sure that auto_predicate=true is set in <install_path>/config/settings.conf before inserting the sample data for the example queries.

The following INSERT DATA query creates a graph named http://anzograph.com/Movies that inserts a small sample of data you can use to test the VERTEX and EDGE functions:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX movies: <http://anzograph.com/Movies/data/>
PREFIX ont: <http://anzograph.com/ontologies/Movies#>
INSERT DATA {
  GRAPH <http://anzograph.com/Movies> {
  # triples for "Tom Hanks" vertex
    movies:TomHanks rdf:type ont:Person .
    movies:TomHanks rdf:type ont:Actor .
    movies:TomHanks ont:name "Tom Hanks" .
    movies:TomHanks ont:born 1956 .
  # triples for "Forrest Gump" vertex
    movies:ForrestGump rdf:type  ont:Movie .
    movies:ForrestGump ont:title "Forrest Gump" .
    movies:ForrestGump ont:release 1994 .
  # edge with properties
  <<movies:TomHanks ont:ACTED_IN movies:ForrestGump>> ont:roles "Forrest" .
  }
}

VERTEX Example

The following example uses the VERTEX function to return the vertexes for actors defined in the sample Movies graph:

SELECT (VERTEX(?s) as ?actor)
FROM <http://anzograph.com/Movies>
WHERE {
  ?s a <http://anzograph.com/ontologies/Movies#Actor> .
}
{
  "id":4294967435,
  "labels":[
    "http://anzograph.com/ontologies/Movies#Person",
    "http://anzograph.com/ontologies/Movies#Actor"
  ],
  "properties":{
    "http://anzograph.com/ontologies/Movies#name":{
      "type":"typed-literal",
      "datatype":"http://www.w3.org/2001/XMLSchema#string",
      "value":"Tom Hanks"
    },
    "http://anzograph.com/ontologies/Movies#born":{
      "type":"typed-literal",
      "datatype":"http://www.w3.org/2001/XMLSchema#int",
      "value":"1956"
    }
  }
}

EDGE Example (Syntax 1)

The following example uses the EDGE function to return information about the ACTED_IN edge:

SELECT ?acted_in
FROM <http://anzograph.com/Movies>
WHERE {
  ?s a <http://anzograph.com/ontologies/Movies#Actor> .
  {
    ?s ?p ?o . 
    BIND (EDGE(?s,?p,?o) as ?acted_in)
  }
  FILTER(?p = <http://anzograph.com/ontologies/Movies#ACTED_IN>)
}

{
  "start":4294967435,
  "end":8589934735,
  "type":"http://anzograph.com/ontologies/Movies#ACTED_IN",
  "properties":{
    "http://anzograph.com/ontologies/Movies#roles":{
      "type":"typed-literal",
      "datatype":"http://www.w3.org/2001/XMLSchema#string",
      "value":"Forrest"
    }
  }
}

Aggregate EDGE Example (Syntax 2)

The following example uses the aggregate EDGE function to return information about the ACTED_IN edge.

SELECT ?s ?p ?o (EDGE(?s,?p,?o,?pp,?pv) as ?edge)
FROM <http://anzograph.com/Movies>
WHERE {
  ?s ?p ?o .
  OPTIONAL { << ?s ?p ?o >> ?pp ?pv }
  FILTER (?p = <http://anzograph.com/ontologies/Movies#ACTED_IN>)
}
GROUP BY ?s ?p ?o

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

Related Topics