Associations

Associations define relationships between entities in the runtime model. This chapter describes how to query and navigate associations.

Navigation properties

The simplest way to access associations is through typed navigation properties. These are generated based on the association roles defined in the Construction Kit.

query {
  runtime {
    systemCommunicationDataPipeline {
      items {
        rtId
        name
        children {
          systemCommunicationPipeline {
            items {
              name
              rtId
              executedBy {
                systemCommunicationAdapter {
                  items {
                    rtId
                    ckTypeId
                    name
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This query traverses: DataPipeline → children → Pipeline → executedBy → Adapter

Generic associations query

For more control over association queries, use the generic associations field with filter parameters.

Parameters

Parameter	Type	Description
roleId	String	Filter by association role (e.g., System/ParentChild)
direction	GraphDirection	INBOUND, OUTBOUND, or ANY
ckId	String	Filter by target entity type
includeIndirect	Boolean	Include transitive associations

Direction

Direction	Description
OUTBOUND	From current entity to related entities (source → target)
INBOUND	From related entities to current entity (target → source)
ANY	Both directions

query
{
    runtime{
        basicTree(rtId: "5fc8fc3d8b2fc75f925e21aa"){
            items{
                rtId
                associations(
                    roleId: "System/ParentChild"
                    direction: INBOUND
                    ckId: "EnergyCommunity/OperatingFacility"
                    includeIndirect: true
                ){
                    items{
                        rtId
                        ckTypeId
                    }
                }
            }
        }
    }
}

Returns all Operating Facilities that are direct or indirect parents of the specified Basic Tree.

{
  "data": {
    "runtime": {
      "basicTree": {
        "items": [
          {
            "rtId": "5fc8fc3d8b2fc75f925e21aa",
            "associations": {
              "items": [
                {
                  "rtId": "693c5b93464d7d9e1396cf1c",
                  "ckTypeId": "EnergyCommunity/OperatingFacility"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Association definitions

To get detailed information about associations including origin and target:

query getRuntimeEntityAssociationsById(
  $rtId: OctoObjectId!
  $ckTypeId: String!
  $direction: GraphDirection!
  $roleId: String
) {
  runtime {
    runtimeEntities(ckId: $ckTypeId, rtId: $rtId) {
      items {
        rtId
        ckTypeId
        associations {
          definitions(direction: $direction, roleId: $roleId) {
            totalCount
            items {
              targetRtId
              targetCkTypeId
              originRtId
              originCkTypeId
              ckAssociationRoleId
            }
          }
        }
      }
    }
  }
}

Definition fields

Field	Description
targetRtId	Runtime ID of the target entity
targetCkTypeId	Type of the target entity
originRtId	Runtime ID of the origin entity
originCkTypeId	Type of the origin entity
ckAssociationRoleId	The association role ID

Querying associated entity attributes

To get attributes of associated entities, use the targets field:

query {
    runtime {
        runtimeEntities(ckId: "Basic/Tree", rtId: "5fc8fc3d8b2fc75f925e21aa") {
            items {
                rtId
                associations {
                    targets(roleId: "System/ParentChild", ckId: "Basic/TreeNode" direction: INBOUND) {
                        items {
                            rtId
                            ckTypeId
                            # Additional attributes of the target entity can be queried here
                        }
                    }
                }
            }
        }
    }
}

The above query retrieves all Basic/TreeNode entities that are parents of the specified Basic/Tree.

{
  "data": {
    "runtime": {
      "runtimeEntities": {
        "items": [
          {
            "rtId": "5fc8fc3d8b2fc75f925e21aa",
            "associations": {
              "targets": {
                "items": [
                  {
                    "rtId": "5fc8fda18b2fc75f925e21ab",
                    "ckTypeId": "Basic/TreeNode"
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Common association roles

Role ID	Description
System/ParentChild	Hierarchical parent-child relationship
System/Ownership	Ownership relationship

The actual roles available depend on your Construction Kit model configuration.

Best practices

1. Use typed navigation properties when the relationship structure is known and fixed
2. Use generic associations query when you need dynamic filtering or traversal
3. Limit indirect queries - transitive queries on large hierarchies can be expensive
4. Filter by type when you only need specific entity types from associations
5. Use pagination on associations with many related entities