How does the process visualization connect to Knowledge Graph data? - johnnyw-aws/aws-iot-twinmaker-samples GitHub Wiki

Entity relationship data in AWS IoT TwinMaker is also modeled as properties of entities (using the RELATIONSHIP data type). e.g. for this FreezerTunnel it has a "belongTo" relationship with the "Freezing" process entity and a "feed" relationship with the VerticalConveyor entity 1(https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/workspaces/cookiefactoryv2/tmdt_project/entities.json#L5095-L5111):

...
{
  "components": {
    ...
    "EquipmentComponent": {
      "componentTypeId": "com.example.cookiefactory.equipment",
      "properties": {
        
        "belongTo": {
          "value": {
            "listValue": [
              {
                "relationshipValue": {
                  "targetEntityId": "Freezing_01f790f8-08e4-401f-b2a2-6bc395178680"
                }
              }
            ]
          },

        },
        "feed": {
          "value": {
            "listValue": [
              {
                "relationshipValue": {
                  "targetEntityId": "VERTICAL_CONVEYOR_d5423f7f-379c-4a97-aae0-3a5c0bcc9116"
                }
              }
            ]
          },
          "definition": {"dataType": {"nestedType": {"type": "RELATIONSHIP"}, "type": "LIST" }}
        }
      }
    }
  },
  ...
  "entityId": "FREEZER_TUNNEL_e12e0733-f5df-4604-8f10-417f49e6d298",
  "entityName": "FREEZER_TUNNEL",
  "parentEntityId": "COOKIE_LINE_5ce9f1d5-61b0-433f-a850-53fa7ca27aa1"
},
...

For entity relationships, the property name is used as a the "relationship name" and the value is the destination entity for the relationship. These entity-entity relationships make up the AWS IoT TwinMaker Knowledge Graph 1(https://docs.aws.amazon.com/iot-twinmaker/latest/guide/tm-knowledge-graph.html) and can be queried using PartiQL through the ExecuteQuery API 2(https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html).

In this demo we configure the AWS IoT TwinMaker Knowledge Graph queries in the Web application 1(https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/workspaces/cookiefactoryv2/CookieFactoryDemo/src/config/project/knowlegeGraph.ts) 2(https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/workspaces/cookiefactoryv2/CookieFactoryDemo/src/config/project/entityData.ts#L182) based on what entities are selected. This enables interactions where an entity is clicked on, the connected entities are retrieved through AWS IoT TwinMaker Knowledge Graph, and then those entities are queried for further relevant details (such as telemetry information)

A sample query used by the Web application:

SELECT processStep, r1, e, r2, equipment FROM EntityGraph
  MATCH (cookieLine)<-[:isChildOf]-(processStepParent)<-[:isChildOf]-(processStep)-[r1]-(e)-[r2]-(equipment), equipment.components AS c
  WHERE cookieLine.entityName = 'COOKIE_LINE'
  AND processStepParent.entityName = 'PROCESS_STEP'
  AND c.componentTypeId = 'com.example.cookiefactory.equipment'`

With annotations on clauses (single-line comments start with -- and end at the end of the line):

-- retrieve the processStep entity, r1 relationship, e entity, r2 relationship from the knowledge graph
SELECT processStep, r1, e, r2, equipment FROM EntityGraph
  
  -- fetch the parts of the graph that match the following entity-relationship pattern:
  --   Note: entities are denoted with parentheses: () 
  --     and relationships with square brackets with hyphens and optional angle bracket
  --     for relationship direction: -[]-, <-[]-
  --   1/ have an entity ('cookieLine') that is the target of an isChildOf relationship with another entity ('processStepParent')
  --   2/ that 'processStepParent' entity is the target of an isChildOf relationship with another entity ('processStep')
  --   3/ that 'processStep' entity has any relationship in any direction ("r1") with any entity ('e')
  --   4/ that 'e' entity has any relationship in any direction ('r2') with an entity ('equipment')
  --   5/ make available the components of the entity 'equipment' as 'c'
  MATCH (cookieLine)<-[:isChildOf]-(processStepParent)<-[:isChildOf]-(processStep)-[r1]-(e)-[r2]-(equipment), equipment.components AS c

  --   6/ the 'cookieline' entity in 1/ must have the entityName 'COOKIE_LINE'
  --   7/ the 'processStepParent' entity in 2/ must have the entityName 'PROCESS_STEP'
  --   8/ the 'equipment' entity in 5/'s component must be for 'com.example.cookiefactory.equipment'
  WHERE cookieLine.entityName = 'COOKIE_LINE'
  AND processStepParent.entityName = 'PROCESS_STEP'
  AND c.componentTypeId = 'com.example.cookiefactory.equipment'`

For more tutorials about PartiQL and AWS IoT TwinMaker Knowledge Graph queries, we recommend checking out our workshop 1(https://catalog.us-east-1.prod.workshops.aws/workshops/93076d98-bdf1-48b8-bfe8-f4039ca1bf25/en-US/1-introduction)