Linked entity

The linked entity feature enables you to combine versions of the same entity from multiple data sources into one combined linked entity.

When to use linked entity

Use linked entity when you need to combine multiple versions of an entity into one combined linked entity where all of the properties and relationships are flattened together.

How to set up data for linked entity retrieval

To use this feature, you must specify hard-coded is known as relationships on one of the entities to the rest For example, to create an entity Site-P101 with is known as relationships to PI.Pump101 and P101:

{

"id": "Site-P101",

"relationships": [

{

"id": "is known as",

"targets": [

{

"id": "PI.Pump101",

"targetBase": 1,

"relationshipType": 1

},

{

"id": "P101",

"targetBase": 1,

"relationshipType": 1

}

]

}

]

}

Filtering on linked entity

Important: Only a filter on a single ID is currently supported.

To retrieve the linked entity, you must specify the ID of either:

• The entity that contains the is known as relationship, or

• One of the entities that is pointed to in one of those is known as targets

  linkedEntity(id: String!)

  Note: Any entities pointed to by is known as cannot be used to filter if they also have their own is known as relationship. In addition, any entities pointed to by two different entities in is known as relationships also cannot be used in filtering.

Using the example above, you could specify one of the following three options, each of which will return all of the properties and relationships as well as entity data:

• linkedEntity(id: "Site-P101")

• linkedEntity(id: "PI.Pump101")

• linkedEntity(id: "P101")

Field reference

LinkedEntity

Linked entity supports the most of the same fields as entity. The main exceptions are that the inbound relationship field is not supported, properties and relationships are combined in linkedProperties and linkedRelationships, and additional entities are specified in linkedEntities:

LinkedEntityHeader

The linkedEntities field in linkedEntity specifies entity header information for all entities connected to the filter entity through is known as relationships. LinkedEntities support everything entities support except for the inbound relationship field and properties and relationships (which are already flattened in the linked entity above):

Examples

Setup

Say that the following are the three entities, which you could retrieve individually with the following query, replacing entityId with each id:

query {

entities( input: {filter: { where: { id: {eq: "{{entityId}}" }}}}){

items {

id

name

description

aliases

securityTags

classId

className

dataSources

version

createdDate

createdBy

modifiedDate

modifiedBy

componentTypes {

id

name

typeCode

}

properties {

id

... on StringProperty {

__typename stringValue

}

... on NumberProperty {

__typename numberValue uom

}

... on BooleanProperty {

__typename booleanValue

}

}

relationships {

id

entityId

targetBase

targetId

relationshipType

}

}

}

}

Site-P101

{

"data": {

"entities": {

"items": [

{

"id": "Site-P101",

"name": "Site-P101",

"description": "AIM Pump Entity 101",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"classId": 2,

"className": "Asset",

"dataSources": [

"AIM"

],

"version": 1,

"createdDate": "2026-04-24T17:32:11.8547836Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T17:32:11.8547836Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "AIM.PUMP",

"name": "Pump",

"typeCode": "OBJECT"

}

],

"properties": [

{

"id": "AT00027",

"__typename": "StringProperty",

"stringValue": "ACME"

},

{

"id": "AT00028",

"__typename": "StringProperty",

"stringValue": "Acme EP-1000"

}

],

"relationships": [

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "PI.Pump101",

"relationshipType": "RELATED"

},

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "P101",

"relationshipType": "RELATED"

},

{

"id": "is located in",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "AIM | Advanced|ELC|PHXA",

"relationshipType": "RELATED"

}

]

}

]

}

}

}

P101

{

"data": {

"entities": {

"items": [

{

"id": "P101",

"name": "P101",

"description": "MES Pump Entity 101",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"classId": 2,

"className": "Asset",

"dataSources": [

"MES"

],

"version": 3,

"createdDate": "2026-04-24T17:31:44.280145Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T20:26:54.473094Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "MES.Asset.Definition.Pump",

"name": "MES.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

],

"properties": [

{

"id": "hourlyCost",

"__typename": "NumberProperty",

"numberValue": 0.6000000238418579,

"uom": null

},

{

"id": "canLogData",

"__typename": "BooleanProperty",

"booleanValue": true

},

{

"id": "equipmentType",

"__typename": "NumberProperty",

"numberValue": 3,

"uom": null

}

],

"relationships": [

{

"id": "assetLocation",

"entityId": "P101",

"targetBase": "ENTITY",

"targetId": "Phoenix.Loc_1",

"relationshipType": "RELATED"

}

]

}

]

}

}

}

PI.Pump101

{

"data": {

"entities": {

"items": [

{

"id": "PI.Pump101",

"name": "PMP-101",

"description": "PI Pump Entity 101 ",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"classId": 2,

"className": "Asset",

"dataSources": [

"PI"

],

"version": 3,

"createdDate": "2026-04-24T17:30:03.5895195Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T19:31:34.7541994Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "PI.Asset.Definition.Pump",

"name": "PI.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

],

"properties": [

{

"id": "Temperature",

"__typename": "NumberProperty",

"numberValue": 140,

"uom": "degree Fahrenheit"

}

],

"relationships": [

{

"id": "IsPrimarilyAChildOf",

"entityId": "PI.Pump101",

"targetBase": "ENTITY",

"targetId": "PI.Plant1",

"relationshipType": "RELATED"

},

{

"id": "FlowRate",

"entityId": "PI.Pump101",

"targetBase": "STREAM",

"targetId": "PI.Pump101Flow",

"relationshipType": "RELATED"

}

]

}

]

}

}

}

Linked entity query on entity with outbound Is Known As

Filtering on entity Site-P101 which contains an outbound is known as relationship to P101 and PI.Pump101:

query {

linkedEntity( id: "Site-P101" ) {

id

name

description

aliases

securityTags

classId

className

dataSources

version

createdDate

createdBy

modifiedDate

modifiedBy

componentTypes {

id

name

typeCode

}

linkedProperties {

id

... on StringProperty {

__typename stringValue

}

... on NumberProperty {

__typename numberValue uom

}

... on BooleanProperty {

__typename booleanValue

}

}

linkedRelationships {

id

entityId

targetBase

targetId

relationshipType

}

linkedEntities {

id

name

classId

description

aliases

securityTags

classId

className

dataSources

version

createdDate

createdBy

modifiedDate

modifiedBy

componentTypes {

id

name

typeCode

}

}

}

}

Here is an example response, where the fields in linkedEntity are populated with the filter entity Site-P101's properties, the rest of the entities in linkedEntities, and the properties and relationships are combined from all three in linkedProperties and linkedRelationships:

{

"data": {

"linkedEntity": {

"id": "Site-P101",

"name": "Site-P101",

"description": "AIM Pump Entity 101 ",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"classId": 2,

"className": "Asset",

"dataSources": [

"AIM"

],

"version": 1,

"createdDate": "2026-04-24T17:32:11.8547836Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T17:32:11.8547836Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "AIM.PUMP",

"name": "Pump",

"typeCode": "OBJECT"

}

],

"linkedProperties": [

{

"id": "AT00027",

"__typename": "StringProperty",

"stringValue": "ACME"

},

{

"id": "AT00028",

"__typename": "StringProperty",

"stringValue": "Acme EP-1000"

},

{

"id": "Temperature",

"__typename": "NumberProperty",

"numberValue": 140,

"uom": "degree Fahrenheit"

},

{

"id": "hourlyCost",

"__typename": "NumberProperty",

"numberValue": 0.6000000238418579,

"uom": null

},

{

"id": "canLogData",

"__typename": "BooleanProperty",

"booleanValue": true

},

{

"id": "equipmentType",

"__typename": "NumberProperty",

"numberValue": 3,

"uom": null

}

],

"linkedRelationships": [

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "PI.Pump101",

"relationshipType": "RELATED"

},

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "P101",

"relationshipType": "RELATED"

},

{

"id": "is located in",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "AIM | Advanced|ELC|PHXA",

"relationshipType": "RELATED"

},

{

"id": "IsPrimarilyAChildOf",

"entityId": "PI.Pump101",

"targetBase": "ENTITY",

"targetId": "PI.Plant1",

"relationshipType": "RELATED"

},

{

"id": "FlowRate",

"entityId": "PI.Pump101",

"targetBase": "STREAM",

"targetId": "PI.Pump101Flow",

"relationshipType": "RELATED"

},

{

"id": "assetLocation",

"entityId": "P101",

"targetBase": "ENTITY",

"targetId": "Phoenix.Loc_1",

"relationshipType": "RELATED"

}

],

"linkedEntities": [

{

"id": "PI.Pump101",

"name": "PMP-101",

"classId": 2,

"description": "PI Pump Entity 101 ",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"className": "Asset",

"dataSources": [

"PI"

],

"version": 3,

"createdDate": "2026-04-24T17:30:03.5895195Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T19:31:34.7541994Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "PI.Asset.Definition.Pump",

"name": "PI.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

]

},

{

"id": "P101",

"name": "P101",

"classId": 2,

"description": "MES Pump Entity 101 ",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"className": "Asset",

"dataSources": [

"MES"

],

"version": 3,

"createdDate": "2026-04-24T17:31:44.280145Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T20:26:54.473094Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "MES.Asset.Definition.Pump",

"name": "MES.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

]

}

]

}

}

}

Linked entity query on entity with inbound Is Known As

Filtering on entity P101 which is connected through an inbound relationship to Site-P101, and PI.Pump101:

query {

linkedEntity( id: "P101" ) {

id

name

description

aliases

securityTags

classId

className

dataSources

version

createdDate

createdBy

modifiedDate

modifiedBy

componentTypes {

id

name

typeCode

}

linkedProperties {

id

... on StringProperty {

__typename stringValue

}

... on NumberProperty {

__typename numberValue uom

}

... on BooleanProperty {

__typename booleanValue

}

}

linkedRelationships {

id

entityId

targetBase

targetId

relationshipType

}

linkedEntities {

id

name

classId

description

aliases

securityTags

classId

className

dataSources

version

createdDate

createdBy

modifiedDate

modifiedBy

componentTypes {

id

name

typeCode

}

}

}

}

Here is an example response, where the fields in linkedEntity are populated with the filter entity P101's properties, the rest of the entities in linkedEntities, and the properties and relationships are combined from all three in linkedProperties and linkedRelationships:

{

"data": {

"linkedEntity": {

"id": "P101",

"name": "P101",

"description": "MES Pump Entity 101",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"classId": 2,

"className": "Asset",

"dataSources": [

"MES"

],

"version": 3,

"createdDate": "2026-04-24T17:31:44.280145Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T20:26:54.473094Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "MES.Asset.Definition.Pump",

"name": "MES.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

],

"linkedProperties": [

{

"id": "hourlyCost",

"__typename": "NumberProperty",

"numberValue": 0.6000000238418579,

"uom": null

},

{

"id": "canLogData",

"__typename": "BooleanProperty",

"booleanValue": true

},

{

"id": "equipmentType",

"__typename": "NumberProperty",

"numberValue": 3,

"uom": null

},

{

"id": "AT00027",

"__typename": "StringProperty",

"stringValue": "ACME"

},

{

"id": "AT00028",

"__typename": "StringProperty",

"stringValue": "Acme EP-1000"

},

{

"id": "Temperature",

"__typename": "NumberProperty",

"numberValue": 140,

"uom": "degree Fahrenheit"

}

],

"linkedRelationships": [

{

"id": "assetLocation",

"entityId": "P101",

"targetBase": "ENTITY",

"targetId": "Phoenix.Loc_1",

"relationshipType": "RELATED"

},

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "PI.Pump101",

"relationshipType": "RELATED"

},

{

"id": "is known as",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "P101",

"relationshipType": "RELATED"

},

{

"id": "is located in",

"entityId": "Site-P101",

"targetBase": "ENTITY",

"targetId": "AIM | Advanced|ELC|PHXA",

"relationshipType": "RELATED"

},

{

"id": "IsPrimarilyAChildOf",

"entityId": "PI.Pump101",

"targetBase": "ENTITY",

"targetId": "PI.Plant1",

"relationshipType": "RELATED"

},

{

"id": "FlowRate",

"entityId": "PI.Pump101",

"targetBase": "STREAM",

"targetId": "PI.Pump101Flow",

"relationshipType": "RELATED"

}

],

"linkedEntities": [

{

"id": "Site-P101",

"name": "Site-P101",

"classId": 2,

"description": "AIM Pump Entity 101",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"className": "Asset",

"dataSources": [

"AIM"

],

"version": 1,

"createdDate": "2026-04-24T17:32:11.8547836Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T17:32:11.8547836Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "AIM.PUMP",

"name": "Pump",

"typeCode": "OBJECT"

}

]

},

{

"id": "PI.Pump101",

"name": "PMP-101",

"classId": 2,

"description": "PI Pump Entity 101",

"aliases": [

"Pump-101"

],

"securityTags": [

"c709f634-9e48-4776-8236-8b9f3b116139"

],

"className": "Asset",

"dataSources": [

"PI"

],

"version": 3,

"createdDate": "2026-04-24T17:30:03.5895195Z",

"createdBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"modifiedDate": "2026-04-24T19:31:34.7541994Z",

"modifiedBy": "74db3d5e-71d9-4c0a-8977-4921b4a55d9c",

"componentTypes": [

{

"id": "PI.Asset.Definition.Pump",

"name": "PI.Asset.Definition.Pump",

"typeCode": "OBJECT"

}

]

}

]

}

}

}

Troubleshooting

Entity ID provided must not have both outbound and inbound relationships

If you see the following message, this means that there are both outbound and inbound is known as relationships on the entity you are trying to filter on. To fix this, you must either:

• Filter on a different entity, or

• Remove either the filtered entity's outbound relationship, or the relationship pointing to this entity

Entity ID provided must only have one inbound relationship

If you see the following message, this means that more than one entity has is known as relationships defined pointing to the entity that you are filtering on. To resolve this either:

• Filter on a different entity, or

• Remove all but one is known as inbound relationships pointing to this entity.