Introduction of SpinalGraph

SpinalGraph is a data schema for grouping together a set of informations and modeling the links between these informations. This data schema works on the "context" layer of the pyramid of informations.

A SpinalGraph is a graph composed essentially of the following objects:

• nodes: (SpinalNode) simple objects representing the data or information (an element) in the grah. The nodes are the support for all the relations between the different information contained in the graph
• relationships: (SpinalRelation) objects representing the interactions between the different elements of the graph
• elements: the elements are the containers of the unit information (ticket, measurement point, BIM object ...) they have a node that represents them in the graph and their interactions with the other elements are represented by the relations between their node and the other nodes of the graph

This structure described before is an example of a graph for a building modeling. It shows the building structure and some informations linked to the building (message, tickets, documents, GTB sensor value ...).

We can define two concept that we are going to use very often :

• A graph is thus an assembly of nodes in relation one with each other. Each node represents a specific data and contains the semantics of the interactions between this data (this element) and the set of other data of the graph.
• A context is a subset of the graph or a part of the graph that we can browse by choosing a starting node and a relation set to "follow". In the previous diagram, the geographical context is represented by the blue nodes linked by blue relations and blue lines. This geographic context is the sub graph that we can browse from the node "Building" and browsing relationships: hasFloor, hasZone and hasEquipment.

Beyond the principles defined above, the concrete implementation of a SpinalGraph relies entirely on the basis of Spinalcore atomic objects. In other words, the nodes objects (SpinalNode), relation (SpinalRelation) as well as the elements (any object) all inherit from the Model object of the Spinalcore library and are therefore natively synchronizable and synchronized like all Spinalcore objects. A SpinalGraph is therefore a structured organization of interacting data that is automatically synchronized between the different organs of a SpinalCore system.

Models

SpinalNode

SpinalNode atomic description have the following attributs :

• info : Information of Node, by default info contain unique id of Node and his type. These attributes can be used for save information outside of element.
• name : the name of the node
• Element : Ptr to get specific datas object. This element contain your ticket, documents, attributes, ...
• Parents :  Ptr of your parents relations.
• RelationListType : Direct SpinalRelation to the children of Node.

We have define three types of SpinalNode to simplify the usage of Graph.

• SpinalNode: Basic Node
• SpinalGraph: Specific Node that describes the starting point of your Graph. It extends from SpinalNode and creates SpinalContext.
• SpinalContext: Specific Node that describes the starting point of your Contexts, It extends from SpinalNode and maintain the relation names of a specific context.

Relations

SpinalRelation are model object too. they represent links between a parents Node and a child Node. A SpinalRelation can have only one unique parent and a lot of children.

SpinalRelation attributes :

• ID: automatic string
• parent : Ptr to his parent
• children : Children container, it can be a SpinalRelationBasic, SpinalRelationPtrLst, SpinalRelationLstPtr

To optimize the memory and the performances of a Spinalcore system involving a Graph, we have implemented three types of relations which, by the use of the atomic model Ptr, allow the automatic loading of all the nodes of a context in limiting the loading to the nodes that are in relation via a "strong" relation. It should be noted that all the relations of the graph make it possible to find the parents of a node. Our three types of relationships are:

1. SPINAL_RELATION_TYPE: "strong" relation for which the parent-child relationship is realized by references. 
2. SPINAL_RELATION_LST_PTR_TYPE: "weak" relationship for which the parent contains a Ptr to the child list. the list of children is only loaded when requested
3. SPINAL_RELATION_PTR_LST_TYPE: "weak" relation for which the parent contains a list of Ptr to his children. We can thus know the number of children nodes but they must be loaded one by one using specific request.

Elements

An Elements is any object you want to save in the graph. Element also need to extend from Spinalcore Model.