secondo/Algebras/PropertyGraph2/sample-orderedrelations/sample-shakespeare/readme.pd

/*
----
This file is part of SECONDO.

Copyright (C) 2012, University in Hagen
Faculty of Mathematic and Computer Science,
Database Systems for New Applications.

SECONDO is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

SECONDO is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with SECONDO; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
----

\tableofcontents

\newpage

1 Overview

The following is a slightly modified example taken from [RWE15]. 

\begin{figure}[h]
    \centerline{
        \includegraphics[width=0.7\textwidth]{graph.eps}}
\end{figure}


2 Prepare data 

2.1 Create database

Create a SECONDO database named "pgraph1" and enter it.

*/
   SECONDO> create database pgraph1; 
   SECONDO> open database pgraph1; 
/*


2.2 Create relations and insert data

The script ~createrels~ will create all node and edge relations and insert
the data to reflect the graph shown above.

*/
   SECONDO> @../Algebras/PropertyGraph2/sample-pregel/sample-shakespeare/createrels 
/*

This script uses operators from ~RelationAlgebra~ and ~UpdateRelation~.
Edge relations names are in uppercase, node relations are using only 
the first character in uppercase. (This convention is used by the PropertyGraphAlgebra)

2.2 Create Ordered-Relations

With the Ordered Relations it is possbile
to query a persistent and non-distributed graph. The Ordered-Realtions can
be created by the following script:

*/
   SECONDO> @../Algebras/PropertyGraph2/sample-pregel/sample-shakespeare/create_orel
/*


3 Creating a property graph 

A property graph has to be defined before matching operators can be
used to query the graph. This is done be registering the node and edge
relations. (This defines the schema of the graph)

*/
   SECONDO> @../Algebras/PropertyGraph2/sample-pregel/sample-shakespeare/create
/*

At first a PropertyGraph object is created. The argument "p1" is 
used to prefix objects in the memory catalog to keep the data
of multiple graphs separated. 

*/

let p1=createpgraph("p1");

/*

To define the schema of the graph, the script ~create~ uses the 
following operators to register the property graph:

  * ~createpgraph(name)~ to create a property graph object

  * ~addnodesrel[relname,fromclause,toclause]~ to register node relations

  * ~addedgesrel[relanme,propertyname, indexname]~ to register edge relations

  * ~addnodeindex[relanme]~ to register node property indexes

This configuration will be saved in the database and will 
be available between sessions.

To get information about the configuration of a property graph 
objects, use the ~info~ operator.

*/
   SECONDO> query p1 info;
/*

4 Loading the graph

To be able to query the property graph, it needs to be loaded with the operator
loadgraphorel.
This will create the statistics of the graph (at the first excecution) and 
additional structures to support the match operators.

*/
   SECONDO> query p1 loadgraphorel;
/*

After loading the graph, the structure of the graph is set to "orel".


5 Querying the property graph

Now the prerequisites have been created to query the graph with persistent
ordered relations.

There are different matching operators available.
All operators are returning a stream of tuples defined by the 
particular output field list.


5.1 Querying by giving a full querytree (match1)

The operator will find all subgraphs that are described
by the querytree by having the same typed node and edge structure 
and passing all filter criteria. Nodes and edges having
an alias (like theater) can be referenced to define the
output field list and in the filter criteria list.
The seach for subgraph matches is done along the query 
tree - so the query tree can be seen as query plan.

This operator has the following arguments:

  1 The property graph object

  2 A stream of nodes that will be the starting positions for a subgraph match

  3 A query tree in list form. This tree describes a subtree that
    should be matched.

  4 Additional filter criteria

  5 Output field list

This query is available in file ~match1~:

*/
   SECONDO> @../Algebras/PropertyGraph/sample-shakespeare/match1
/*


5.2 Querying by giving a querytree (match2)

This operator is not using a query tree anymore. It is given
the subgraph pattern as a graph. The starting point - and so 
the query plan - will be choosen automatically by taking 
statistical data into account. The operator will open the 
corresponding edge list automatically - no node stream is necessary 
anymore.

This operator has the following arguments:

  1 The property graph object

  2 The query graph in list form
  
  3 Additional filter criteria

  4 Output field list


This query is available in file ~match2~:

*/
   SECONDO> @../Algebras/PropertyGraph/sample-shakespeare/match2
/*


5.3 Using Cypher language for querying (match3)

The readability of the previous expression as list is limited for
complex queries. The graph query language cypher tries to improve that by
having a syntax that is very intuitive and "whiteboard friendly".
(See [CYP20] for more details)
Nodes and edges are drawn like (x)--$>$(y) with some annotations.

This operator has the following arguments:

  1 The property graph object

  2 The query coded as cypher expression


This query is available in file ~match3~:

*/
   SECONDO> @../Algebras/PropertyGraph/sample-shakespeare/match3
/*
   

6 References

  [RWE15] Ian Robinson, Jim Webber, and Emil Eifrem: \emph{Graph Databases}, O'Reilly Media, Inc., 2015.

  [CYP20] https://neo4j.com/docs/cypher-manual/current/

*/