Skip to main content
Version: 2.0

Manager Models

Platform Version 2.0

API Version 1.0

Introduction​

A manager model is a specification for a graph. A manager model shows what nodes, relationships, and properties are allowed and how they can be structured. Manager models are versioned to keep track of previous specifications of the graph. A manager model is itself a graph, comprised of several predefined nodes and relationships. Manager models are not enforced like with ONgDB constraints. The manager model allows a user to manage their graph schema so that the desired nodes/relationships/property types can be created in the Graphgrid UI.

note

We use the term Relationship and Edge interchangeably.

Environment​

Manager requires the following integrations: ONgDB 1.0+

Manager Models represented by the Graph​

Manager models are graphs themselves consisting of Node and Relationships. The node labels include Manager, ManagerVersions, NodeTypes, EdgeTypes, Constraints, Properties, and PropertyImpls. They are connected by several relationship types and can be viewed in the Overview below. Manager Models can also be represented by a ManagerModelPolicy.

Overview​

Below is a visual overview of the different nodes and relationships one will see in a ManagerModel. Note this does not include the contextual Manager or versioning ManagerVersion nodes.

Nodes in Manager Models​

There are several nodes that comprise a ManagerModel, with Manager and ManagerVersion nodes keeping track of the overall Manager Model context and version. Keep in mind all nodes have a grn property to uniquely identify them, and are not mentioned in each node explanation.

Manager​

This node contains a name property for identification and is the "head" of the manager model. The Manager node serves as a base for any ManagerModels. It connects to the latest ManagerVersion node.

ManagerVersion​

These nodes are used to version the same ManagerModel. Each ManagerVersion is connected to all the nodes of the ManagerModel through a MANAGER_SPEC relationship (see below). They ManagerVersions are versioned through a version integer property, and connected to its next and previous version through the MANAGER_CHAIN relationship.

NodeType​

NodeType defines a unique node type (label) through its key, definition, and namespace. It also has displayValue and a grn property which serves as a unique identifier. A NodeType's key is unique and is the "label" for its nodes. Its definition is a short string describing/defining the NodeTypes purpose context. A NodeTypes namespace specifies the grn namespace for nodes of this type, by default it is gg.

EdgeType​

EdgeType is similar to the NodeType, except instead of defining a node label for the graph an EdgeType defines a relationship type. It has a unique key as well, which is the "type" for its relationships. It has a definition which describes/defines the EdgeTypes purpose/context.

Constraint​

A Constraint node is used to define what NodeTypes are allowed to connect to each other by which EdgeType. It does this by connecting to NodeType and EdgeType nodes with START_NODE_TYPE, END_NODE_TYPE and ALLOWED_EDGE_TYPE relationships which can be seen in the Overview section above. Each Constraint node has a definition property which describes/defines the Constraint purpose/context, min/max properties which are constraint settings that determine the number of edges allowed to exist between two node types, and a displayValue property.

caution

The Constraint node does not define an ONgDB constraint! This constraint is totally separate and independent of ONgDB Constraints/Indexes!

Property​

A Property node is used to define its PropertyImpl nodes. The Property node has a key property which is the property name. It has a dataType property which is used to specify the data type of the property (STRING, BOOLEAN, LIST, etc.) It also has isEditable and isDeletable properties.

PropertyImpl​

A PropertyImpl node is an implementation of a Property node that can be on a certain node or relationship. A PropertyImpl is defined by exactly one Property node through a DEFINES relationship. NodeType and EdgeType nodes have a property connect to the PropertyImpl node through a HAS_PROPERTY relationship. PropertyImpl nodes have three required boolean properties: isRequired, isUnique and isIndexed. The last, isIndexed refers to whether ONgDB has an index on that property for the connecting NodeType/EdgeType.

PropertyImpl nodes also have three optional override settings: displayValue, isEditable, and isDeletable. These are referred to as overrides because they override the defaults on the Property node that define them.

Each PropertyImpl is connected to exactly one NodeType or EdgeType.

Relationships in Manager Models​

Several of the Relationships have been shown/mentioned in the sections Overview and Nodes in Manager Models. The relationships of a Manager Model connect the various NodeType, EdgeType, Constraint, Property, and ManagerVersion nodes.

MANAGER_CHAIN​

This connects a previous ManagerVersion node with the next ManagerVersion node. It is also used to connect the latest ManagerVersion to the Manager node. In the example below the Manager node is blue, and the two ManagerVersion nodes are orange, with the most recent ManagerVersion connecting to the Manager node.

MANAGER_SPEC​

This relationship is used to connect the ManagerVersion node to all the Manager Model nodes, such as NodeType, EdgeType, Constraint, Property, and PropertyImpl.

The example picture below shows the ManagerVersion node (orange) connecting to several other Manager Model nodes through the MANAGER_SPEC relationship.

START_NODE_TYPE, END_NODE_TYPE, ALLOWED_EDGE_TYPE​

The START_NODE_TYPE and END_NODE_TYPE are directed from Constraints to NodeType nodes. The START_NODE_TYPE signifies that a Constraint node starts with that NodeType while the END_NODE_TYPE signifies that a Constraint node ends with that NodeType.

The ALLOWED_EDGE_TYPE relationships are directed from Constraint to EdgeType nodes. They signify the allowed EdgeType for the Constraint.

Each Constraint has exactly one START_NODE_TYPE, END_NODE_TYPE and ALLOWED_EDGE_TYPE.

For example:

Here we have a "PersonDirectorOfOrganization" Constraint node (blue), a "Person" NodeType node and an "Organization" NodeType node (pink), and then a DIRECTOR_OF EdgeType node (red).

DEFINES and HAS_PROPERTY​

The DEFINES relationships are directed from a Property to each of its PropertyImpl nodes.

The HAS_PROPERTY connects a NodeType/EdgeType to one of its PropertyImpl nodes. This is used to specify which properties a NodeType/EdgeType can have.

Below is an example of the DEFINES and the HAS_PROPERTY relationships. The NodeType "Person" (pink) connects to the two PropertyImpl (orange) nodes which are defined by the two Property (purple) nodes. In the graphs that follow a Manager model like this the Person nodes would only have two properties, a grn and a name property.

An Example of a Manager Model Graph​

Below is an example of a small Manager Model graph. It consists of:

  • One Manager node; 'test' (Blue)
  • One ManagerVersion (Orange)
  • Two NodeTypes; Person and Organization (Dark Orange)
  • One EdgeType; DIRECTOR_OF (Periwinkle)
  • One Constraint; PersonDirectorOfOrganization (Yellow)
  • Six PropertyImpl; (Pink)
  • Three Property nodes; (Purple)

The MANAGER_SPEC relationships cause a bit of crowding, but the general structure can be seen in the example:

Manager Model Policy​

Creating a Manager Model manually and ensuring all the versioning and properties are set correctly on each node would be both time-consuming for the user and increases the chance of error. Instead of creating everything from scratch we instead use a ManagerModelPolicy to generate the Manager Models on the graph.

A ManagerModelPolicy (MMP) is a JSON policy which is used to generate the NodeType, EdgeType, Property, PropertyImpl, and versioning nodes of a manager model. ManagerModelPolicies are saved to S3 and endpoints expose APIs to generate the Manager Model.

The Manager Model Policy is used by filling in some basics of the Manager Model in a JSON format, and then having the boot-manager application determine and generate the remainder.

Manager Model Policy Structure​

There are five main parts of each policy:

  • Metadata
  • NodeTypes
  • EdgeTypes
  • Constraints
  • Properties

Let us take a look at an entire example policy before diving into each section:

{
    "metadata": {
        "displayName": "gg-test-mmp",
        "description": "An example ManagerModelPolicy.",
        "createdAt": "2019-12-19T00:00:00+00:00",
        "updatedAt": "2020-01-06T15:30:43+00:00",
        "versions": []
    },
    "nodeTypes": {
        "Person": {
            "definition": "A person.",
            "displayValue": "Person",
            "properties": {
                "grn": {
                    "isRequired": true,
                    "isUnique": true,
                    "isIndexed": true
                },
                "name": {
                    "isRequired": true,
                    "isUnique": false,
                    "isIndexed": false,
                    "displayValue": "personName"
                }
            }
        },
        "Organization": {
            "definition": "An organization.",
            "displayValue": "Organization",
            "properties": {
                "grn": {
                    "isRequired": true,
                    "isUnique": true,
                    "isIndexed": true,
                    "displayValue": "orgGrn"
                },
                "name": {
                    "isRequired": false,
                    "isUnique": false,
                    "isIndexed": false
                },
                "orgId": {
                    "isRequired": true,
                    "isUnique": true,
                    "isIndexed": false
                }
            }
        }
    },
    "edgeTypes": {
        "DIRECTOR_OF": {
            "definition": "This edge indicates the start node is the director of the end node.",
            "displayValue": "DIRECTOR OF",
            "properties": {
                "grn": {
                    "isRequired": true,
                    "isUnique": true,
                    "isIndexed": true
                }
            }
        }
    },
    "constraints": {
        "PersonDirectorOfOrganization": {
            "startNodeType": "Person",
            "endNodeType": "Organization",
            "edgeType": "DIRECTOR_OF",
            "min": 0,
            "max": -1
        }
    },
    "properties": {
        "grn": {
            "dataType": "String",
            "definition": "Unique Identifier",
            "displayValue": "grn",
            "isEditable": false,
            "isDeletable": false
        },
        "name": {
            "dataType": "String",
            "definition": "Entity name",
            "displayValue": "name",
            "isEditable": true,
            "isDeletable": false
        },
        "orgId": {
            "dataType": "String",
            "definition": "Unique Organization Identifier",
            "displayValue": "orgId",
            "isEditable": false,
            "isDeletable": false
        }
    }
}

Metadata​

This holds information about the ManagerModelPolicy such as its name, description, createdAt/updatedAt dates, as well as previous versions of the same ManagerModelPolicy.

NodeTypes​

The NodeTypes section defines which NodeType nodes should be in the ManagerModel. The map keys are used as for the NodeType nodes key properties. The definition and displayValue are used as their respective properties as well on the NodeType node. Optionally it can have a namespace.

The "properties" map is a validated map that define the PropertyImpls that will be created for the NodeType. So in our example the "Person" NodeType will create (and connect to) two PropertyImpls grn and name. These propertyImpl keys must match up with a defined Property in the "properties" section. The boolean properties will default to false if not specified.

EdgeTypes​

The EdgeTypes section defines the EdgeTypes of the Manager Model. It is nearly identical to NodeTypes section. The only difference is that it cannot have namespace property.

Constraints​

The Constraints section defines the Constraints of the Manager Model. The startNodeType, endNodeType, and edgeType are all validated against the defined NodeTypes and EdgeTypes in the policy.

Properties​

The Properties section defines the Property nodes of the Manager Model. The example below defines the three properties grn, name, and orgId.
When creating the Manager Model Policy Properties you DO NOT NEED to type out booleans, they will default to false.

"properties": {
    "grn": {
      "dataType": "String",
      "definition": "Unique Identifier",
      "displayValue": "grn",
      "isEditable": false,
      "isDeletable": false
    },
    "name": {
      "dataType": "String",
      "definition": "Entity name",
      "displayValue": "name",
      "isEditable": true,
      "isDeletable": false
    },
    "orgId": {
      "dataType": "String",
      "definition": "Unique Organization Identifier",
      "displayValue": "orgId",
      "isEditable": false,
      "isDeletable": false
    }
  }

Manager Model Policy Endpoints​

Load Manager Policy​

Gets the Manager Model Policy from S3/MinIO

Base URL: /1.0/manager/model/policy/loadPolicy/{{clusterName}}/{{policyName}}
Method: GET

ParmetersDescription
clusterNameThe clusterName (folder) that the policy is stored in.
policyNameThe policy name.

Response:

Returns the Manager Model Policy as a JSON response.

200 OK

Generate Manager Model Policy​

Base URL: /1.0/manager/model/policy/{{clusterName}}/generateManagerModelPolicy/{{managerModelPolicyName}} Method: POST

ParametersDescription
clusterNameThe clusterName (folder) that the policy should be saved in.
policyNameThe policy name.

There are two optional data keys to include in the request, includeLabels and excludeRelationships.

Request​
curl --location '${API_BASE}/1.0/manager/model/policy/default/generateManagerPolicy/default-manager-model-policy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 67b0129a-080d-45ce-b4fc-b68688a8e4c8' \
--data '{
    "includeLabels": [
        "Person",
        "Movie"
    ],
    "excludeRelationships":[]
}'

Save Manager Model Policy​

Saves and returns the Manager Model Policy in the request body.

Base URL: /1.0/manager/model/policy/savePolicy/{{clusterName}}/{{policyName}}
Method: POST

ParametersDescription
clusterNameThe clusterName (folder) that the policy should be saved in.
policyNameThe policy name.

The Request Body can be any valid Manager Model Policy.

Response:

Returns the saved Manager Model Policy
200 OK

danger

When editing the Manager Model Policy, ensure that the correct version is being edited. If using the Generate Manager Model Policy endpoint, previous versions will be included in a key, versions, at the top of the policy. The most recent version will be toward the bottom of the policy.

Generate Manager Model Graph​

Saves and returns the Manager Model Policy in the request body.

Base URL: /1.0/manager/model/policy/generateManagerModelGraph/{{clusterName}}/{{policyName}}/{{managerGrn}}
Method: POST

ParametersDescription
clusterNameThe clusterName (folder) that the policy should be saved in.
policyNameThe policy name.
managerGrnThe grn of the Manager node that the Manager Model should be generated for.

The Request Body can be any valid Manager Model Policy.

Response: Returns the saved Manager Model Policy
200 OK