Association Roles

Association Roles define the relationship types between entities. Each role specifies the multiplicity and naming for both directions of the relationship (inbound and outbound).

List Association Roles

Retrieve all association roles:

query getCkAssociationRoles($after: String, $first: Int, $ckModelIds: [String]) {
  constructionKit {
    associationRoles(after: $after, first: $first, ckModelIds: $ckModelIds) {
      totalCount
      items {
        ckAssociationRoleId {
          fullName
          semanticVersionedFullName
        }
      }
    }
  }
}

Response

{
  "data": {
    "constructionKit": {
      "associationRoles": {
        "totalCount": 12,
        "items": [
          {
            "ckAssociationRoleId": {
              "fullName": "System-1.0.3/Parent-1",
              "semanticVersionedFullName": "System/Parent"
            }
          },
          {
            "ckAssociationRoleId": {
              "fullName": "EnergyCommunity-1.0.0/AssociatedCustomer-1",
              "semanticVersionedFullName": "EnergyCommunity/AssociatedCustomer"
            }
          }
        ]
      }
    }
  }
}

Filter by Model

Retrieve association roles from specific models:

query {
  constructionKit {
    associationRoles(ckModelIds: ["EnergyCommunity-1"]) {
      totalCount
      items {
        ckAssociationRoleId {
          fullName
        }
      }
    }
  }
}

Association Role Details

Retrieve detailed information about a specific association role:

query getCkAssociationRoleDetails($roleId: String) {
  constructionKit {
    associationRoles(ckId: $roleId) {
      totalCount
      items {
        ckAssociationRoleId {
          fullName
          semanticVersionedFullName
        }
        description
        inboundMultiplicity
        inboundName
        outboundMultiplicity
        outboundName
      }
    }
  }
}

Variables:

{
  "roleId": "EnergyCommunity-1.0.0/AssociatedCustomer-1"
}

Response

{
  "data": {
    "constructionKit": {
      "associationRoles": {
        "totalCount": 1,
        "items": [
          {
            "ckAssociationRoleId": {
              "fullName": "EnergyCommunity-1.0.0/AssociatedCustomer-1",
              "semanticVersionedFullName": "EnergyCommunity/AssociatedCustomer"
            },
            "description": "Links customers to their operating facilities",
            "inboundMultiplicity": "N",
            "inboundName": "customers",
            "outboundMultiplicity": "N",
            "outboundName": "facilities"
          }
        ]
      }
    }
  }
}

Understanding Association Directions

An association role defines a relationship that can be navigated in two directions:

┌──────────────┐                           ┌─────────────────────┐
│   Customer   │ ──── facilities ────────► │  OperatingFacility  │
│              │ ◄──── customers ───────── │                     │
└──────────────┘                           └─────────────────────┘
       │                                            │
       │                                            │
   OUTBOUND                                     INBOUND
   (source)                                    (target)

Direction	Property Name	From Entity	To Entity	Multiplicity
Outbound	facilities	Customer	OperatingFacility	N
Inbound	customers	OperatingFacility	Customer	N

Search Association Roles

Search for roles by name:

query {
  constructionKit {
    associationRoles(
      searchFilter: {
        searchTerm: "Customer"
        type: ATTRIBUTE_FILTER
        attributePaths: ["ckAssociationRoleId.fullName"]
      }
    ) {
      items {
        ckAssociationRoleId {
          fullName
        }
        inboundName
        outboundName
      }
    }
  }
}

Viewing Type Associations

To see which association roles are used by a specific type, query the type's associations:

query {
  constructionKit {
    types(ckId: "EnergyCommunity-1.0.0/Customer-1") {
      items {
        ckTypeId {
          fullName
        }
        associations {
          out {
            owned {
              roleId {
                fullName
              }
              navigationPropertyName
              multiplicity
              targetCkTypeId {
                fullName
              }
            }
          }
          in {
            owned {
              roleId {
                fullName
              }
              navigationPropertyName
              multiplicity
              originCkTypeId {
                fullName
              }
            }
          }
        }
      }
    }
  }
}

See Types for more details on querying type associations.

Association Role Fields

CkAssociationRole

Field	Type	Description
ckAssociationRoleId	CkAssociationRoleId	The association role identifier
description	String	Description of the relationship
inboundMultiplicity	Multiplicity	Cardinality from target to source
inboundName	String	Navigation property name for inbound direction
outboundMultiplicity	Multiplicity	Cardinality from source to target
outboundName	String	Navigation property name for outbound direction

Multiplicity

Value	Description
ZERO_OR_ONE	Optional single relationship (0..1)
ONE	Required single relationship (1)
N	Multiple relationships (0..*)

Common Association Patterns

Parent-Child (Composition)

A strong ownership relationship where children cannot exist without their parent:

{
  "ckAssociationRoleId": { "fullName": "System-1.0.3/Parent-1" },
  "inboundMultiplicity": "N",
  "inboundName": "children",
  "outboundMultiplicity": "ZERO_OR_ONE",
  "outboundName": "parent"
}

Many-to-Many

A loose relationship where both sides can have multiple associations:

{
  "ckAssociationRoleId": { "fullName": "EnergyCommunity-1.0.0/AssociatedCustomer-1" },
  "inboundMultiplicity": "N",
  "inboundName": "customers",
  "outboundMultiplicity": "N",
  "outboundName": "facilities"
}

One-to-Many

One entity owns multiple related entities:

{
  "ckAssociationRoleId": { "fullName": "Basic-1.0.0/Owner-1" },
  "inboundMultiplicity": "N",
  "inboundName": "ownedItems",
  "outboundMultiplicity": "ONE",
  "outboundName": "owner"
}